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Chapter 1 Introduction 


1.1 Before You Begin 


The AdvaInform SQL*Connect Programming option is available for users having a need to 
work with advanced Oracle based applications. Most user’s who wants to crete smaller 
applications are better off using AdvaInform User API or ODBC/SQL access from PC’s. 


The AdvaInform SQL*Connect Programming option provides a User library for Advant OCS 
objects accessible to any SQL client. 


Advalnform software packages for information management make information available in real 
time for environmental, business, quality and cost decisions. Thanks to the client/server 
architecture, users can monitor the production efficiency on-line through their own PC’s, in that 
way staying in touch with the process and ultimately in-creasing the plant's competitiveness. 


Multiple operator stations with AdvaCommand can concurrently show trend displays of 
historical data, stored in AdvaInform History. This means that operators can examine 
production as well as quality and environmental data from current time to years back. 


AdvalInform software can act as a server of information, providing Manufacturing Execution 
Systems (MES) and Enterprise Resource Planning (ERP) systems with the access they need to 
production data. This type of information transfer used to require specialized gateways and 
programming, but with Advant OCS, standard SQL calls are all that is required. 


The functions for information management are collected from three different software families: 
AdvalInform, AdvaTalk and AdvaBuild. 


° Advalnform is a software family for information management. 
° AdvaTalk is a software family which connects 3’rd party software to Advant OCS. 
° AdvaBuild is a software family for application engineering and development. 


Throughout this document the term AdvaInform will be used in most cases except when a 
specific function provided as an AdvaTalk or AdvaBuild function is described. 


The AdvaInform SQL*Connect Programming option provides a PL/SQL library to Advant 
OCS objects accessible for any SQL client. 


With SQL*Connect Programming you can execute Advant OCS object operations as if the 
objects are relational database entities. This lets you write powerful application programs using 
the Programmer Pro*C option, the SQL*Connect Programming option, the AdvaInform 
SQL*Connect functionality included in the AdvaInform Basic Software and the features 
provided by the relational database itself and SQL*NET. 
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Figure 1-1. Usage of SQL*Connect Programming 


Example: Assume you want to read relational data from external relational databases over 
SQL*NET (typical recipes, product planning information) and use the data to update process 
control parameters. Then SQL*Connect programming together with SQL*Plus/PL/SQL and the 
Programmer 2000-Pro*C option provides just the tools for you. 


The guide is intended for those who are responsible for writing SQL applications for the Advant 
OCS. As a prerequisite to using this book, you should already have some system-level training 
or experience with the Advant OCS, and also have some experience with PL/ SQL and 
relational databases. 


This guide is not a PL/SQL users or reference guide! For detailed information regarding the 
SQL language, refer to Oracles SQL Reference manual(s). 


To learn more about AdvaInform SQL*Connect and other AdvaInform functions, it is 
recommended that you attend the appropriate training courses provided by ABB Industrial 
Systems training centers. 
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1.2 Equipment Requirements 


SQL*Connect Programming is an IMS option designed to run in conjunction with the 
Advalnform Basic Functions. It runs on all Advant Station 500 Series IMS workstations. 


1.3 How to Use This Book 
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If you are an experienced Advant OCS user, you can go straight to the chapter or section dealing 
with the topic you are interested in for the moment. The Table of Contents and/or the Index 
helps you find where to look. 


If you are an inexperienced user - you don’t know very much about Advant OCS or SQL - it’s 
recommended that you start by reading all of Chapters | and 3. The rest of the guide, including 
the appendix, can be seen more as reference information. 
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This book is organized into chapters and sections as shown in Figure 1-2. 
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Data Types 
Release and Constants 
History 

Basic Objects 
Terminology Packages 
Overview of the Advalnform 
Advalnform History 
SQL*Connect Packages 
Environment 

Numeric Log 
User Interface Configuration 

Package 


Basic Services 
Package 


Chapter 1, Introduction 


Maintenance 


Appendix A 


Preventive 
Maintenance 


Error Messages 


Figure 1-2. Organization of Manual 


Basic information about SQL*Connect Programming 


Chapter 2, Installation 


Installation information. 


Data Types 
Constants 
Capabilities 


Basic Object 
Packages 


History 
Packages - 
gtHistory 


Numeric Log 
Configuration 
Data Package - 
gtNLOG 
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Chapter 3, Advalnform SQL*Connect Programming 


Describes how to use AdvaInform SQL*Connect Programming 


Chapter 4, Maintenance & Troubleshooting 


Describes error messages. 


Appendix A, Declarations for the SQL*Connect Programming 


Describes the declaration for the SQL*Connect Programming 


1.3.2 Differences Between Systems with Master and MOD 300 Software 


MOD 300 and Master 
This guide covers both MOD and Master. This is handled in two ways: 


° In some cases when the operation/commands differs, two alternatives are described - one 
for MOD and one for Master 


° When the difference is restricted to for example object type only, the MOD alternative is 
described in brackets: (MOD: text). 


1.4 Conventions 


Table 1-1 shows the conventions used in this guide: 


Table 1-1. Conventions 


Example Type of information 
.. refer to the Advalnform References to other books are written in Italics. 
SQL*Connect Programming 
User’s Guide. 
.. the very first time you .. Italics used for emphasis. 
.. press the Return key .. The names of keyboard keys are written in Times (same as for 


the rest of the text) and in the same way as on the keyboard 
(initial capital letter for example) in plain text. 


.. press the space bar .. Lowercase letters are used for the name of a key that is not 
labeled on the keyboard. 

.. press <Return> .. In tables and procedures, angle brackets replace the word 
“key.” 

Click or Single Click Click the left mouse button 


Double Click Double click the left mouse button 
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Table 1-1. Conventions (Continued) 


Example 


.. SCtrl-C> .. 


.. press the OK button .. 


.. select New from the File 
ment .. 


.. select File - New ... 


.. enter TIC132 into .. 


Type of information 


A dash is used to indicate that you must simultaneously press 
several keys - Ctrl and C in the example. 


Push and toggle buttons are written the same way as they 
appear on the display. Also, in descriptions, tables and 
procedures, the word “button” is used in conjunction with its 
name. 


Initial capital letters are used for the name of menu items. 


Short for select New from the File menu (above). 


In a tutorial, for example, you may be told to enter a value in a 
field. The value is then written bold faced. 


1.5 Related Documentation 


Table 1-2 lists all documentation related to AdvaInform SQL*Connect Programming. 


Table 1-2. Related Documentation 


Category Title 


Description 


Station 


Advant Station 500 Series IMS User’s Guide 


This book provides instructions for system 
administration functions such as backup and 
restore. 


Software 


Advalnform Basic Functions User’s Guide 


This book describes the basic functions that 
support all Advalnform software packages. 


Software Release Notes for SQL*Net & ODBC 


Part of a delivery. Describes for example the 
installation procedure. You can’t say 
“describes for example”. You have to say 
exactly what information is provided (or at least 
cover the most important subjects). Same 
applies to all other books below 


Software 


Advalnform SQL*Connect User’s Guide 


This book describes how to configure and 
operate various RDB (Relational Data Base) 
functions in Advant OCS products based on 
Advalnform SQL*Connect. 


Other 


Advalnform Object Types Reference Manual 


This book describes the accessible objects in 
the Advant OCS. 


Other PL/SQL User’s Guide and Reference 


A32542 (can be ordered through the Advant 
OCS price list) 
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Table 1-3 lists the major milestones in the development of AdvalInform SQL*Connect 


Programming. 


Table 1-3. AdvalInform SQL*Connect Programming release history 


Version 


Description 


1.0 


Initial version. 


1.7 Terminology 


Table 1-4 shows a list of terms associated with AdvaInform SQL*Connect Programming you 
should be familiar with before you go on reading. 


Term 
Advant OCS 
AS 5xx 
Attribute 


Client 


Command 


Core System 
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Table 1-4. Terminology 


Description 
Advant Open Control System. 
Short for Advant Station 5xx. For example AS 530. 


Describes the public data of the object (see below). The 
result of an application is most commonly stored in 
attributes. Attributes also contain configured public 
information. Applications (other objects) can request the 
object’s public data through the core system, using 
subscriptions. 


A process, such as a Web browser, that interfaces to one or 
more users, sends requests to a server, and presents the 
results of those requests to the users. See also server. 


A command is a request for an action for an object. Asa 
result, the object performs the requested action. 


All nodes in the Advant OCS communicate through the 
Core System. The Core System provides services for 
system applications. Using these services, the system 
applications can communicate, no matter if they reside in 
the same node or in separate nodes of different types. The 
Type Directory (see below) is a part of the Core System, 
and contains information about all object types known to the 
Advant OCS. 
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Term 


Control network 
(Master) 


Database Table 


Database View 


DCS 
Display Element 


ES 


External/Internal nodes 
(computers) 


IMS 


Table 1-4. Terminology (Continued) 


Description 


A network that connects different types of Advant Station 
and, Advant Controllers used to supervise and control a 
specific part of a plant. There can be a maximum of nine 
Control networks. It is possible to exchange data between a 
Control network and the Plant network (see below), and 
also between different Control networks through the Plant 
network. The types of data exchange that are allowed is 
controlled by the set up of the MasterGate filtering 
functions. 


A Table in the RDB is the place holder for information. 
Tables are organized in rows and columns. A row contains 
information for an RDB instance (for example, an Al in 
Advalnform). A column contains information for a specific 
attribute. 


A Database View in the RDB (see below) context can be 
seen as a “window” or “virtual table” through which you can 
read information from one or more database tables. 


Distributed Control System. 


A configurable presentation component (or element) that 
represents one or more Advant OCS object. 


Short for Advant Station 500 Series Engineering Station. 


An external node is a node which is not a member of the 
Advant OCS concept (internal nodes). An external node 
can access for example an IMS through the X-protocol or 
via SQL*Net. 


Example of an external node: A PC connected to the plant 
network. 


Short for Advant Station 500 Series Information 
Management Station. 
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Term 


Advalnform Basic 
Objects 


IMS menu 


Key 


Object 


Object Directory 
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Table 1-4. Terminology (Continued) 


Description 


Advalnform Basic Objects are instances of pre-defined 

object types used for storage of Advalnform data. They can 

for example be logged by Advalnform History and be used 

in Advalnform applications (user and system). These are 

the available Basic Objects: 

*«  Al,AO: Floating point objects 

. DI,DO: Boolean objects (On/Off) 

* TXT: String (text) objects 

. DAT: Objects of type Boolean, Integer, or Floating point 

*  coExecutor: Object used to execute any Advalnform 
program or script 

¢ — coRTM: Object for Run Time Measurement (for motor 
drives normally) 


*  coBasicCalc: Object used to handle various types of 
calculations. Number of inputs to a calculation can be 
in he range 2 to 10. Examples of calculations: sum, 
average. 


The main entry to IMS. Thatis, the menu that pops up when 
you log in to IMS. 


A unique identifier used in a relational database. Also the 
term Primary key is used. 


In the Advant OCS concept, a combination of data and 

associated procedures (operations) are represented by 

objects. 

Examples of objects are: 

. Process objects. For example PIDCON 

. History logs 

«  Advalnform Basic Objects (Al, AO, DI, DO ... and so 
on, see Advalnform Basic Objects). Refer to the 
Advalnform Object Types Reference Manual for a 
detailed description. 


A place holder for descriptions of object instances (see 
Type Directory below). The Object Directory is a part of the 
Core System (see above). 
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Term 


ODBC 


OS 


Package 


PL/SQL 


Programmer 2000 - 
Pro*C 


RDB 


RDBMS 


Server 


SQL 


SQL*Net 


System Messages 


Table 1-4. Terminology (Continued) 


Description 


Open DataBase Connectivity. With ODBC installed, you can 
use normal SQL commands to access RDB data. ODBC is 
one of several methods available to get RDB data into a 
PC. 


ODBC supports, for example, Oracle and is normally 
started via an icon on the PC’s Control panel. 


Short for Advant Station 500 Series Operator Station. 


In this context, a group of PL/SQL functions and 
procedures. 


Oracle’s proprietary extension to the SQL language. 
PL/SQL adds procedural and other constructs to SQL that 
make it suitable for writing applications. 


An option that makes it possible to access the relational 
database from a C or C++ application program. 


Relational DataBase. See also Database Table and 
Database View. 


Relational DataBase Management System. A computer 
software program, such as the Oracle RDBMS, that 
manages a relational database. 


A process that executes requests on behalf of another 
process (the client) whose main purpose is to interface the 
user. 


Advalnform SQL*Connect contains a client and a server 
part. 


Structured Query Language. The industry-standard 
language for interfacing to relational databases such as 
Oracle. 


An Oracle software product required to connect an external 
PC to an IMS, thus enabling transfer of RDB data and 
commands in both directions. SQL*Net is available for a 
number of communication protocols. In IMS, SQL*Net for 
TCP/IP is used. 


Advalnform system function which handles and presents 
system messages. 


3BSE 014 220R0001 


Advalnform® SQL*Connect® Programming User’s Guide 
Section 1.8 Overview of the Advalnform SQL*Connect Environment 


Table 1-4. Terminology (Continued) 


Term Description 
TCP/IP Transmission Control Protocol/Internet Protocol. 
Type Directory A table containing descriptions of object types. It’s important 


to be aware of that the Type Directory is a part of the Core 
System (see above) whereas the tables and views are parts 
of the RDB. 


1.8 Overview of the Advalnform SQL*Connect Environment 


AdvaInform SQL*Connect Programming provides SQL read access (on demand, event driven 
or cyclic) as well as write access to objects in Advant OCS. Object instances in the Advant OCS 
can be accessed by name without having to know their physical addresses. 


AdvaInform SQL*Connect Programming is based on Oracle Open Gateway Technology. 


Figure 1-3 gives an overview of AdvaInform SQL*Connect Programming. 


Client application/tool with SQL support 
Access through: 


- SQL 
™ | = Pusat 


Oooo | -Pro*c 


SQL 


Advalnform SQL*Connect Procedural Packages 


Oracle RDBMS 


SQL*Net 


Advalnform SQL*Connect Programming 


SQL*Connect 
Oracle part 


ABB Part 


Symbol name translation Demand/cyclic/event/operation subscriptions 


Advant OCS system > 


Figure 1-3. Advalnform SQL*Connect Programming - Overview 
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1.9 User Interface 


There are a number of ways to access data through the AdvaInform SQL*Connect 
Programming: 


° Via an AdvaInform option such as AdvaInform Reports. Consult the applicable user’s 
guide (for example, the Advalnform Reports User’s Guide) for details. 


° Interactively - There are two user interfaces included in the AdvaInform Basic Functions 
to access Advant OCS objects interactively: 


— The Database Access window, see Figure 1-4. 


This window is opened via the Database Access menu item in the Station menu. At 
the SQL> prompt, you can enter PL/SQL statements to access Advant OCS object 
data. Instead of typing in SQL commands, you can execute a script file. 


Copyright (c) Oracle Corporation 1979, 1994. All rights reserved. 


Connected to: 

Oracle? Server Release 7.3.2.3.0 - Production Release 
With the distributed option 

PL/SQL Release 2.3.2.3.0 - Production 


SQL> SET SERVEROUTPUT ON 
SQL> DECLARE 
status GT.AccessStatus; 
BEGIN 
IF gtAl.put_VALUE(’AIC71_1’, 23.45, status) != GTI.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(’Function failed’); 
ELSE 
DBMS_OUTPUT.PUT_LINE(’Access status code = ’ || status.codes); 
END IF; 
END; 


PL/SQL procedure successfully completed. 


sQu> 


Figure 1-4. The Database Access window 


° Via the Programmer 2000 - Pro*C option 


You can also use the Programmer 2000 - Pro*C option to write your own C or C++ 
programs to access the relational database. This lets you combine the functionality of the 
AdvaInform SQL*Connect Programming and the relational database itself. 


From a performance point of view it is normally best to implement applications using 
Pro*C rather than through scripts using SQL and PL/SQL. 


Typical applications where the Pro*C pre-compiler is recommended are: 


— For reading relational database data from external relational databases (typical 
recipes and product planning information) and use the data to operate your process as 
optimally as possible. 
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— For reading information from the Advant OCS (historical information, object 
attributes) and writing that information into an external database. 


The main application can then be started and supervised by the AdvaInform Basic 
Functions software. 


An example of an embedded PL/SQL application and a make file is provided in the 
Connect /examples directory. The names of the files are procex.pc and 
ProcMakefile respectively. 
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Chapter 2 Installation 


2.1 General 


2.1.1 HP-UX 


See the Advant Station 500 IMS User’s Guide for installation of AdvaInform SQL*Connect 
Programming option. 
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Chapter 3 Advalnform SQL*Connect Programming 


3.1 Introduction 


The AdvaInform SQL*Connect Programming option provides a number of programming 
(procedural) packages. Operations on Advant OCS objects, for example update of an attribute, 
can only be executed with SQL*Connect Programming procedures, not through direct SQL 
commands. This chapter includes a reference manual helping you with all the details to be able 
to implement your SQL applications. 


User Application or 
Oracle Tool 


Oracle Server 


Procedural Gateway 


Advant OCS 


RDBMS 


Figure 3-1. Advalnform SQL*Connect Procedural Gateway 


The complete SQL*Connect Programming option is divided into three main packages: 
° The Basic Objects packages 


These packages provide special read and write sub-packages for some of the Master Basic 
Objects. The supported object types are: 
AI, AO, DI, DO, DAT, TEXT, PIDCON, RATIOSTN and MANSTN. 
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If none of the Basic Objects packages meets your demands, or if you want to access other 
object types, you can use some of the generic functions in the Basic Services package (see 
below). 


For MOD 300, no Basic Objects Packages are defined because the operations on MOD 300 
object types are generic, that is, they can be created from the attribute names. Instead, use 
the generic functions in the Basic Services package. 


For a detailed description of the services, refer to Section 3.5, Basic Objects Packages. 
° The AdvalInform History package 


This package contains a number of special functions for AdvaInform History. If this 
package does not meet your demands, then try to use the generic functions in the Basic 
Services package (see below). 


For a detailed description of the services, refer to Section 3.6, AdvaInform History 
Package. 


° The Basic Services package 


This package contains some general functions (for time conversion for example) plus a 
number of so called generic functions. Generic, in this context, means that a function is not 
dedicated for a specific object type but can be used for any type. 


For the Basic Objects and AdvaInform History packages, above, it has been mentioned 
that if they don’t meet your requirements, try using some function in the Basic Services 
package. 


For a detailed description of the services, refer to Section 3.8, Basic Services Package. 


To make use of the various services in the SQL*Connect Programming option, you need 
information about data types and pre-defined constants. You can find this type of information in 
Appendix A, Declarations for the SQL*Connect Programming. 


3.2 How to Work with the SQL*Connect Programming packages 


3.2.1 User 


To be able to use the application builder and executor you must log in as an authorized user. Ask 
your system manger for help, or add a new user with the User Definition tool started from the 
IMS menu. 


3.2.2 Environment 


The IMS default environment must be set up. Customer applications are preferably located in 
the /home/opt/advant/IMS/customer directory. 


BU applications should be located in the /home/opt /advant/IMS/adaptions 
directory. 
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You can use the default editor (started from the IMS menu) or a user defined editor. Note that it 
is possible to change the default editor. Ask your system manager for help or consult the 
Advalnform Basic Functions User’s Guide to learn how to do that. 


3.2.4 Compile/Link 


3.2.5 Execution 


SQL and PL/SQL applications 
SQL or PL/SQL applications are compiled by Oracle tools when executed. 


Embedded SQL or PL/SQL applications 


An optional Programmer Pro*C licence can be included in IMS. This means that embedded 
SQL or PL/SQL applications can be built (Embedded SQL or PL/SQL means SQL or PL/SQL 
statements embedded in a high-level source program, for example C code). 


You can find examples of an embedded PL/SQL application and a makefile in the 
Connect /examples directory. The names of the files are procex.pc and 
ProcMakefile respectively. 


PL/SQL applications 
Execute PL/SQL applications in the Database Access window or from a Terminal Window: 


# sqlplus / < application.sql 


Embedded PL/SQL applications 
Embedded PL/SQL applications can be executed by an IMS user in a Terminal Window: 
# application 


Embedded PL/SQL applications can also be added to the supervised start-up of IMS. For 
information about supervised start-up, refer to the Advalnform Basic Functions User’s Guide. 


3.2.6 Trace and Debug 
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The SQL Procedural Services are not quite easy to debug. However, some information is 
available in the /var/opt/advant/log/Connect/gtwrite.err file. 


The trace level is set in the /opt /advant/Connect/bin/gtwrite.sh file. 


Set the G[_TRACE and BCI_TRACE parameters to a value between 0 (no trace) and 10 (full 
trace). GT_TRACE is the trace level for the Oracle part and BCI_TRACKE is the trace level for 
the Advant part. 
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3.3 Tutorial - How to Execute an Operation on a Remote Object 


The only way to execute an operation on a process object is via a program using a User API 
service, or via a script or a program using SQL Procedural Services (described in Chapter 4, 
Maintenance & Troubleshooting). 


This tutorial uses the SQL Procedural Services. The program will update the value attribute of 


an AI object instance named AIC71_10. 


NOTE 


The Programmer 2000 Pro*C option must be installed in order to use SQL from a 
program. 


3.3.1 Preparations 


Before you begin the tutorial, you must create or identify an AI object in a Controller that you 
are allowed to update. Then, substitute the name of that object for AIC71_10 (used in the 
tutorial as an example). 


You must also have an IMS user of, at least, category Engineer. Refer to Section 3.2.1, User. 


3.3.2 Step by step description 
Follow the step-by-step description below to run the tutorial: 
1. Log in. You must be an IMS user of, at least, category Engineer. 
2. Edit the PL/SQL block. 


Use the IMS default editor (choose Editor from the Station menu) or some other editor 
you might prefer. Program name is tutorial. File extension is . sql. 


3. Save your program in your working directory. 
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Then enter the following program code (remember to replace AIC71_10 with the name 


of your object!): 


-- tutorial.sql 


-- Set the VALUE attribute of AIC71_10 instance to 12.34 


SET SERVEROUTPUT ON 


DECLARE 
opArg LONG; 
result NUMBER; 
accessStatus GT.AccessStatus; 
objectName VARCHAR2 (256) ; 
BEGIN 
objectName := ‘AIC71_10’; 


-—- Initialize out buffer 
opArg := NULL; 


-- Initialize operation data 


GT. buildData(GT.dcVALUE_CHANGE_DCX, opArg); -- opCode 
GT. buildData(GT.dcACT_VALUE_DCX, opArg) ; -- opProp 
GT.buildData(GT.dcPROG, opArg); -- typeOfReq 
GT.buildData(0, opArg); -—- eventLog 
GT.buildData(0, opArg); -- dialogId 
GT.buildData(12.34, opArg); -- aValue 
GT.buildData(0, opArg); -- dValue 
GT.buildData(0, opArg); -- status 
GT.buildData(0, opArg); -- textIndex 
-- Perform demand 

result := GT.executeOperation (‘AI’, 

objectName, 
‘ORDER’, 
opArg, 
accessStatus) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.executeOperation error = * | | result); 
RETURN; 

END IF; 


-—- Print object access status 


DBMS_OUTPUT.PUT_LINE (‘Access 
accessst 
DBMS_OUTPUT.PU LINE (‘Access 


accessst 


status codes = * | | 
atus.codes); 
status flags = * | | 
atus.flags); 
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4. Choose IMS Terminal Window from the Station menu to open a terminal window. 
5. Move to your working directory 
Enter command: # cd working directory 
6. Execute your example program. 
Enter command: # sqlplus / < tutorial.sql 
7. Watch the result. 
You should now see something like this on your screen: 
Access status codes = 1 
Access status flags = 0 


The new value of the object should be 12.34. 


3.4 Data Types and Constants 


Following data type definitions are included in the GT package (see Section 3.8, Basic Services 
Package): 


° IntArray, used for array of number variables. 

° StringArray, used for array of string variables. 

° RowIdArray, used for array of row id variables. 

° AccessStatus, used for object access status variables. 

These data types are used by functions in the GT package and Basic Objects packages. 
See Section A.1, Data Types for details on pre-defined data types. 


Constants are declared for all function return codes, all access status codes and flags, data types 
etc. See Section A.2, Constants for a full description of GT constants. 


3.5 Basic Objects Packages 


3.5.1 General 
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AdvaInform SQL*Connect Programming contains special read and write packages for some 
Master Basic Objects: AI, AO, DI, DO, DAT, TEXT, PIDCON, RATIOSTN and MANSTN. If 
these packages does not meet your demands, or if you want to access other object types, then 
use the generic functions described in Section 3.8, Basic Services Package. 


For MOD 300, no Basic Objects Packages are defined because the operations on MOD 300 
object types are generic, that is, they can be created from the attribute names. Instead, use the 
generic functions, see Section 3.8, Basic Services Package. 


For information on data types for the Basic Objects Packages, refer to Section A.4, Basic Object 
Packages. 
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3.5.2 Overview 


The name of the packet for an object type is gtobject type. Example: gtATI is the packet 
name for object type AI. Below is a list of functions included in each object package. 


Basic Object Functions 


Usage 


put_attribute 


Update one attribute of one object instance 


get_attribute 


Read one attribute of one object instance 


getCyclic_attribute 


Read one attribute of one object instance cyclically 


getOnEvent_attribute 


Read one attribute of one object instance on event 


3.5.3 put_attribute 


Packages with functions to update attributes of one object that can be changed with an 
operation. The functions can be used on demand and with Do-Request functionality. One 
package per object type. 


Synopsis 


Function used for single executions: 


NUMBER put_attribute ( 


objectName IN VARCHAR2, 
value IN <attribute type>, 
accessStatus OUT GT .AccessStatus) ; 


Function used for initializing Do-Request demand: 


NUMBER put_attribute ( 


uniqueIdentity IN NUMBER, 
objectName IN VARCHAR2, 
value IN <attribute type>); 


Function used for reading access status after do-Request call: 


NUMBER put_attribute ( 


Parameters 
uniqueldentity 
objectName 
value 


accessStatus 


uniqueIdentity IN NUMBER, 
objectName IN VARCHAR2, 
accessStatus OUT GT .AccessStatus) ; 


[in] 
[in] 
[in] 


[out] 


unique integer value which identifies the request 
name of the object instance 
new attribute value 


status of the object access, 
see Section A.2.3, Object access status codes. 
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Description 


The put_attribute functions sets the value of an objects attribute. See Section A.4, Basic Object 
Packages for information about data types for the Basic Objects packages. 


NOTE 


Only one ‘put’ function per object is allowed when using Do-Request. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
REFERENCE Invalid unique identity 
Example 


-- The AI object type has a HI_LIM1 attribute and we want to set the 
-—- value of that attribute to 90.0 for the object instance AIC71_1: 


DECLARE 
status GT.AccessStatus; 
result NUMBER; 
value FLOAT; 
BEGIN 
result := gtAI.put_HI_LIM1(‘AIC71_1’, 90.0, status); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
END IF; 
IF status.codes != GT.OBJ_SUCCESS THEN 


status.codes); 
status.flags) ; 


DBMS_OUTPUT.PUT_LINE (‘Access status codes = 
DBMS_OUTPUT.PUT_LINE (‘Access status flags 
END IF; 


[| 
an | 


END; 


3.5.4 get_aitribute 


Packages with functions to read attributes of an object. The functions can be used on demand 
and with DoRequest functionality. There is one package per object type. 


Synopsis 


Function used for one shot demands: 
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NUMBER get_attribute ( 


objectName IN 
value OUT 
accessStatus ouT 


Function used for initializing DoRequest demand: 


NUMBER get_attribute ( 
uniquelIdentity IN 
objectName IN 


Function used for reading object data after doRequest call: 


NUMBER get_attribute ( 


Section 3.5.4 get_attribute 


VARCHAR2, 
<attribute type>, 
GT .AccessStatus) ; 


NUMBER, 
VARCHAR2) ; 


NUMBER, 

VARCHAR2, 
<attribute type>, 
GT .AccessStatus) ; 


unique integer value which identifies the request 


see Section A.2.3, Object access status codes. 


uniqueldentity IN 
objectName IN 
value OUT 
accessStatus OUT 
Parameters 
uniqueldentity [in] 
objectName [in] name of the object instance 
value [out] attribute value 
accessStatus [out] status of the object access, 
Description 


The get_attribute functions reads the value of an objects attribute. See Section A.4, Basic 
Object Packages for information about data types for the Basic Objects packages. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
REFERENCE Invalid unique identity 
Example 


-- The AI object type has a HI_LIM1 attribute and we want to read the 
—- value of that attribute for the object instance AIC71_1: 
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status GT.AccessStatus; 
result NUMBER; 
value FLOAT; 
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BEGIN 
result := gtAI.get_HI_LIM1(‘AIC71_1’, value, status); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
END IF; 
IF status.codes != GT.OBJ_SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE (‘Access status codes = * | | status.codes) ; 
DBMS_OUTPUT.PUT_LINE(‘Access status flags = * | | status.flags); 
ELSE 
DBMS_OUTPUT.PUT_LINE(*‘HI_LIM1 = * || value); 
END IF; 
END; 


3.5.5 getCyclic_attribute 


Packages with functions to read attributes of an object cyclically. There is one package per 


object type. 

Synopsis 

NUMBER getCyclic_attribute ( 
objectName IN VARCHAR2, 
cycleTime IN DOUBLE PRECISION) ; 

Parameters 

objectName [in] name of the object instance 

cycleTime [in] time in seconds between each operation 

Description 


The getCyclic_attribute functions reads the value of an objects attribute with a cyclic interval. 
See Section A.4, Basic Object Packages for information about data types for the Basic Objects 
packages. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
Example 
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-- Get the VALUE attribute from AIC71_1 instance and the STATUS 
-- attribute from DIC71_1 instance cyclically with a cycle time of 10 
-- seconds during a period of 30 seconds. 


SET SERVEROUTPUT ON 


DECLARE 
objectName VARCHAR2 (256) ; 
accessStatus GT.AccessStatus; 
result NUMBER; 
timeOut FLOAT; 
index NUMBER; 
elementType NUMBER; 
elementName VARCHAR2 (100); 
elementData LONG; 
elementVal NUMBER; 
rowIndexes GT.RowIdArray; 
numberOfRows NUMBER; 
BEGIN 
-—- Set up subscriptions 
result := gtAl.getCyclic_VALUE (‘AIC71_1’, 10.0); 
result := gtDI.getCyclic_STATUS (‘DIC71_1’, 10.0); 


-- Wait for data in 30 seconds 


timeOut := 30.0; 
WHILE timeOut > 0.0 LOOP 
result := GT.getData(timeOut, rowIndexes, numberOfRows) ; 
FOR index IN 1..numberOfRows LOOP 
result := GT.getObjectData (rowIndexes (index), 
objectName, 
accessStatus, 
elementType, 
elementName, 


elementData) ; 
DBMS_OUTPU . PUT_LINE (objectName | re |accessStatus.codes) ; 
IF elementType = GT.ATTRIBUTE THEN 
-- Print attribute value 


result := GT.extractData(elementData, elementVal); 
DBMS_OUTPUT.PUT_LINE(||* *||elementName||* = *‘||elementval) ; 
END IF; 
END LOOP; 
END LOOP; 
GT.CancelAll; 


END; 


Example Output 


AIC71_1 256 
VALUE = 56 

DIC71_1 67 
STATUS = 5678 

AIC71_1 256 
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VALUE = 56 
DIC71_1. 67 
STATUS = 5678 
AIC71_1 256 
VALUE = 56 
DIC71_1 67 
STATUS = 5678 


3.5.6 getOnEvent_attribute 


Packages with functions to read attributes of an object on event. One package per object type. 


Synopsis 
NUMBER getOnEvent_attribute ( 
objectName IN VARCHAR2) ; 
Parameters 
objectName [in] name of the object instance 
Description 


The getOnEvent_attribute functions reads the value of an objects attribute on events. See 
Section A.4, Basic Object Packages for information about data types for the Basic Objects 
packages. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
Example 


—- Get the VALUE attribute from AIC71_1 instance and the STATUS 
-- attribute from DIC71_1 instance on event. 
—-- Wait for a period of one minute. 


SET SERVEROUTPUT ON 


DECLARE 
objectName VARCHAR2 (256); 
accessStatus GT.AccessStatus; 
result NUMBER; 
timeOut FLOAT; 
index NUMBER; 
elementType NUMBER; 
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elementName VARCHAR2 (100) ; 
elementData LONG; 
elementVal NUMBER; 
rowIndexes GT.RowIdArray; 
numberOfRows NUMBER; 


EGIN 

—- Set up subscriptions 

result := gtAI.getOnEvent_VALUE (*AIC71_1’); 
result := gtDI.getOnEvent_STATUS (‘DIC71_1’); 


-—- Wait for data in 60 seconds 
timeOut := 60.0; 
WHILE timeOut > 0.0 LOOP 
result := GT.getData(timeOut, rowIndexes, numberOfRows) ; 
FOR index IN 1..numberOfRows LOOP 
result := GT.getObjectData (rowIndexes (index), 
objectName, 
accessStatus, 
elementType, 
elementName, 
elementData) ; 
DBMS_OUTPU . PUT_LINE (objectName | |accessStatus.codes) ; 
IF elementType = GT.ATTRIBUTE THEN 
—-- Print attribute value 
result := GT.extractData(elementData, elementVal); 
DBMS_OUTPUT .PUT_LINE ( | |elementName | |elementVal) ; 
END IF; 
END LOOP; 
END LOOP; 
GT.CancelAll; 


YVoN 


Nak OS 


YVoN 


END; 


Example Output 


AIC71_1 256 


VALUE = 56 
AIC71_1 256 
VALUE = 66 
DICGWL 367 
STATUS = 5678 
DIC71_1 67 
STATUS = 5667 
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3.6 Advalnform History Package 


3.6.1 General 


3.6.2 Overview 


AdvaInform SQL*Connect Programming contains special functions for AdvaInform History. If 
the AdvaInform History package does not meet your demands, then try to use the generic 
functions described in Section 3.8, Basic Services Package. 


For a description of data types, refer to Section A.5, History Package - gtHistory. 


The name of the Advalnform History package is gtHistory. Below is a list of the functions 
included in the package. 


History Package Functions 


activate Activates log or loggroup 
deactivate Deactivates log or loggroup 
getNumericEntry Reads entries from a numerical log 
addNumericEntry Adds one entry to a numerical log 
modNumericEntry Modify one entry in a numerical log 
getMessageEntry Reads entries from a message log 
addMessageEntry Adds one entry to a message log 


3.6.3 activate 


3-14 


Activates log or loggroup. 


Synopsis 
NUMBER activate ( 

logName IN VARCHAR2, 

accessStatus OUT GT.AccessStatus) ; 
Parameters 
logName [in] log name 
accessStatus [out] status of the object access, 

see Section A.2.3, Object access status codes. 

Description 


The activate function activates one log or loggroup. 
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3.6.4 deactivate 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
NO_PRIVILEGE Privilege not allowed 
Example 
DECLARE 
result NUMBER; 
logName VARCHAR2 (30) := ‘SHSAIC73_1-1-0'; 
status GT.AccessStatus; 
BEGIN 
result := gtHISTORY.activate(logName, status); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
END IF; 


DBMS_OUTPUT.PUT_LINE(‘*Access status codes 
DBMS_OUTPUT.PUT_LINE(‘*Access status flags 
END; 


status.codes); 
status.flags); 


- || 
|| 


Deactivates log or loggroup. 


Synopsis 
NUMBER deactivate ( 

logName IN VARCHAR2, 

accessStatus OUT GT .AccessStatus) ; 
Parameters 
logName [in] log name 
accessStatus [out] status of the object access, 

see Section A.2.3, Object access status codes. 

Description 


The deactivate function deactivates one log or loggroup. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
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RESOURCE_LACK 
ALLOCATION 
ILLEGAL_NAME 
NO_PRIVILEGE 


Could not allocate memory 
Could not allocate resource 
Illegal characters in object name 
Privilege not allowed 


Example 
DECLARE 
result NUMBER; 
logName VARCHAR2 (30) := ‘SHSAIC73_1-1-0'; 
status GT.AccessStatus; 
BEGIN 
result := gtHISTORY.deactivate(logName, status); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
END IF; 


END; 


3.6.5 getNumericEntry 


3-16 


Reads entries from a numerical log. 


DBMS_OUTPUT.PUT_LINE (‘Access status codes = * 
DBMS_OUTPUT.PUT_LINE(‘*Access status flags 


status.codes); 
status.flags); 


Synopsis 
NUMBER getNumericEntry ( 
logName IN VARCHAR2, 
calcAlgorithm IN NUMBER, 
dataCollection IN NUMBER, 
dataSelector IN NUMBER, 
timeJustification IN NUMBER, 
time IN DATE, 
microSeconds IN NUMBER, 
timeInterval IN NUMBER, 
initialValueEntries IN NUMBER, 
cycleiInterval IN NUMBER, 
cyclicValueEntries IN NUMBER, 
entry OUT gtHISTORY .NUMERIC_ENTRY_UT, 
accessStatus OUT GT .AccessStatus) ; 
Parameters 
logName [in] log name 
calcAlgorithm [in] calculation algorithm, see Table A-22. 
dataCollection [in] data collection, see Table A-18. 
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dataSelector [in] data selector, see Table A-21. 
timeJustification [in] time justification, see Table A-16. 
time [in] time 

microSeconds [in] micro seconds part of time 
timelnterval [in] time interval (seconds) 

initial ValueEntries [in] initial value entries 

cycleInterval [in] cycle interval (seconds) 
cyclicValueEntries [in] number of cyclic data entries 
entry [out] numerical log entries, 


see Section A.5.1, Data Types. 


accessStatus [out] status of the object access, 
see Section A.2.3, Object access status codes. 


Description 


The getNumericEntry function retrieves entries from an AdvaInform History numerical log. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
NO_PRIVILEGE Privilege not allowed 
Example 
DECLARE 

status NUMBER; 

arriIndex NUMBER; 

logName VARCHAR2 (256) := ‘TTD_10_71_1_1’; 


logEntries gtHISTORY .NUMERIC_ENTRY_UT; 
accessStatus GT.AccessStatus; 


BEGIN 
DBMS_OUTPUT .ENABLE (100000) ; 


status := gtHISTORY.getNumericEntry (logName, 
gtHISTORY.hsWILDCARD, 
gtHISTORY.hsRAW, 
gtHISTORY.hsCURRENT, 
gtHISTORY.hsEND_TIME, 
GT.ZERO_TIME, 
0, 
60*60, 
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400, 
0, 
0, 
logEntries 
accessStatus); 
IF status != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE (‘gtHISTORY.getNumericEntry error = * | | 
status); 
RETURN; 
END IF; 
IF accessStatus.codes != GT.OBJ_SUCCESS THEN 


DBMS_OUTPUT.PUT_LINE (‘Access status codes = * | | 
accessStatus.codes); 
DBMS_OUTPUT.PU ,INE(‘Access status flags = * | | 

accessStatus.flags); 


RETURN; 
END IF; 


IF logEntries.last_is = GT.OPEN_ARRAY_IS_EMPTY THEN 
DBMS_OUTPUT.PUT_LINE(*> History data @ * || 
SYSDATE | | 


X 


from * | | 
logName | | 
‘ WAS NOT RECEIVED !’); 


ELSE 
FOR arrIndex IN 1..logEntries.last_is LOOP 
DBMS_OUTPUT.PUT_LINE(‘-> DATA# *‘||arrIndex||’ : @ * || 
TO_CHAR (GT.timeStampToDate (logEntries.seconds (arrIndex) +2*60*60), 
‘YYYY-MM-DD HH24:MI:ss’) || 


X 


| logEntries.microSeconds (arrIndex) | | 
| logEntries.entryValue (arrIndex) | | 

‘ Status: * | | 

logEntries.entryStatus (arrIndex) ); 


X 


a | 


END LOOP; 
END IF; 
END; 


3.6.6 addNumericEntry 


Adds one entry to a numerical log. 


Synopsis 

NUMBER addNumericEntry ( 
logName IN VARCHAR2, 
entryValue IN NUMBER, 
entryStatus IN NUMBER, 
time IN DATE, 
microSeconds IN NUMBER, 
accessStatus OUT GT .AccessStatus) ; 
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Parameters 
logName [in] log name 
entry Value [in] log entry value 
entryStatus [in] log entry status 
time [in] time 
microSeconds [in] micro seconds part of time 
accessStatus [out] status of the object access, 
see Section A.2.3, Object access status codes. 
Description 


The addNumericEntry function adds one entry to an Advalnform History numerical log. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
NO_PRIVILEGE Privilege not allowed 
Example 
DECLARE 

status NUMBER; 

accessStatus GT.AccessStatus; 

operation VARCHAR2 (30); 

logName VARCHAR2 (256); 

objectType VARCHAR2 (256) ; 

arguments LONG := NULL; 


entryValue NUMBER; 
objectStatus NUMBER; 
time DATE; 
microSeconds NUMBER; 


BEGIN 

logName := ‘SHSOBA73_1-1-0’; 

objectType := ‘NLog’; 

operation := ‘AddNumericValue’; 

entryValue := 123.0; 

objectStatus := 1; 

time := SYSDATE; 

microSeconds := 0; 

status := gtHISTORY.addNumericEntry (logName, 
entryValue, 
objectStatus, 
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IF status != GT.SUCCESS TH 


EN 


DBMS_OUTPUT.PUT_LIN 


RETURN; 
END IF; 


IF accessStatus.codes 


status); 


DBMS_OUTPUT.PUT_LIN 


RETURN; 
END IF; 


DBMS_OUTPUT.PUT_LIN 


time, 
microSeconds, 
accessStatus); 


E(‘gtHISTORY.addNumericEntry error = * | | 


GT.OBJ_SUCCESS THEN 
E(‘Access status codes = * | | 
accessStatus.codes); 

E (‘Access status flags = 


| 
4 


accessStatus.flags) ; 


DBMS_OUTPUT.PUT_LINE(‘logName @ 
TO_CHAR(time, ‘YYYY-MM-DD HH24:MI:SS’) || 


\ 


*.0000 = * || entryValue || 
’ successfully added ...’); 
END; 
3.6.7 modNumericEntry 
Modifies one entry in a numerical log. 
Synopsis 
NUMBER modNumericEntry ( 
logName IN VARCHAR2, 
entryValue IN NUMBER, 
entryStatus IN NUMBER, 
time IN DATE, 
microSeconds IN NUMBER, 
accessStatus OUT GT .AccessStatus) ; 
Parameters 
logName [in] log name 
entry Value [in] log entry value 
entryStatus [in] log entry status 
time [in] time 


microSeconds 


accessStatus 


[in] 


[out] 


micro seconds part of time 


status of the object access, 
see Section A.2.3, Object access status codes. 
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Description 


The modNumericEntry function modifies one entry in an AdvaInform History numerical log. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
NO_PRIVILEGE Privilege not allowed 

Example 


See addNumericEntry function example. 


3.6.8 getMessageEntry 


Reads entries from a message log. 


Synopsis 
NUMBER getMessageEntry ( 
logName IN VARCHAR2, 
timeJustification IN NUMBER, 
time IN DATE, 
microSeconds IN NUMBER, 
timeInterval IN DATE, 
initialMsgEntries IN NUMBER, 
cyclicMsgEntries IN NUMBER, 
entry OUT gtHISTORY .MESSAGE_ENTRY_LUT, 
accessStatus OUT GT.AccessStatus) ; 
Parameters 
logName [in] log name 
timeJustification [in] time justification, see Table A-16. 
time [in] time 
microSeconds [in] micro seconds part of time 
timelnterval [in] time interval 
initialMsgEntries [in] initial message entries 
cyclicMsgEntries [in] number of cyclic data entries 
entry [out] message log entries, 


see Section A.5.1, Data Types 


3BSE 014 220R0001 3-21 


Advalnform® SQL*Connect® Programming User’s Guide 
Chapter 3 Advalnform SQL*Connect Programming 


accessStatus [out] status of the object access, 
see Section A.2.3, Object access status codes. 


Description 


The getMessageEntry function retrieves entries from an Advalnform History message log. 


Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
NO_PRIVILEGE Privilege not allowed 

Example 


See addMessageEntry function example. 


3.6.9 addMessageEntry 


Adds one entry to a message log. 


Synopsis 

NUMBER addMessageEntry ( 
logName IN VARCHAR2, 
entryValue IN VARCHAR2, 
time IN DATE, 
microSeconds IN NUMBER, 
accessStatus OUT GT .AccessStatus) ; 

Parameters 

logName [in] log name 

entry Value [in] log entry value 

time [in] time 

microSeconds [in] micro seconds part of time 

accessStatus [out] status of the object access, 


see Section A.2.3, Object access status codes. 


Description 


The addMessageEntry function adds one entry to an Advalnform History message log. 
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Return Value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
NO_PRIVILEGE Privilege not allowed 

Example 


See addNumericEntry function example. 
3.7 Numerical Log Configuration Package 


3.7.1 General 


AdvaInform SQL*Connect Programming contains special functions for retrieving configuration 
data of History Numerical Logs. 


For a description of data types, refer to Section A.6, Numerical Log Configuration Data 
Package - gtNLOG. 


3.7.2 Overview 


The name of the numerical log configuration data package is gt NLOG. Below is a list of the 
functions included in the package. 


Numerical Log Configuration Data 
Package Functions 


getConfData Retrieve configuration data for one or all numerical logs. 
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3.7.3 getConfData 


Retrieves configuration data about one or all History numerical log. 


Synopsis 


Function for retrieving configuration data from one numerical log: 


NUMBER getConfData ( 


logName IN VARCHAR2, 
confDataRecord OUT gtNLOG.ConfDataRecord, 
accessStatus OUT GT.AccessStatus) ; 


Function for retrieving configuration data for all numerical logs: 


NUMBER getConfData ( 


receiveNewLogs IN BOOLEAN, 
confDataArray OUT gtNLOG.ConfDataRecord, 
accessStatus OUT GT .AccessStatus) ; 
Parameters 
logName [in] log name 
receiveNewLogs [in] flag, set to TRUE to start a new query for all configuration data, 
set to FALSE to retrieve rest of data (as long as the function 
returns MORE) 
confDataRecord [out] configuration data 
confDataArray [out] configuration data array 
accessStatus [out] status of the object access, 
see Section A.2.3, Object access status codes. 
Description 


The getConfData function retrieves configuration data about one or all History numerical logs. 
The receiveNewLogs flag is used when the query has to be divided into several subqueries. The 
flag shall always be set to TRUE the first time. If there are more data the function returns 
MORE. and subsequent calls to the function should have the receiveNewLogs flag set to 
FALSE until the function returns SUCCESS. See Section A.6, Numerical Log Configuration 
Data Package - gtNLOG for a full description of the configuration data record. 


Return Value 


SUCCESS 
EXE_FAILED 
RESOURCE_LACK 
ALLOCATION 
ILLEGAL_NAME 
NO_PRIVILEGE 
MORE 
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Successful completion 

System function has failed 
Could not allocate memory 
Could not allocate resource 
Illegal characters in object name 
Privilege not allowed 

There are more data to fetch 
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Example 


SET SERVEROUTPUT ON 


DECLARE 
result NUMBER; 
logName VARCHAR2 (256) ; 
confDataRecord gtNLOG.ConfDataRecord; 
accessStatus GT.AccessStatus; 

BEGIN 


DBMS_OUTPUT.ENABLE (100000) ; 


logName := '’SHSAIC71_1,VALUE-1-0'; 
result := gtNLOG.getConfData (logName, 
confDataRecord, 
accessStatus); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(’ gtNLOG.getConfData error =’ || 
result); 
RETURN; 
END IF; 


DBMS_OUTPUT.PUT_LINE (’NAME=’ || confDataRecord. NAMI 
DBMS_OUTPUT.PUT_LINE(’ACCESS_NAME = ’ || 
confDataRecord.ACCESS_NAME) ; 
DBMS_OUTPUT . PUT_LINE (’ DATA_SOURC1 
confDataRecord.DATA_SOURCE) ; 
DBMS_OUTPUT.PUT_LINE (’ ALIGNMENT_TIMEUNIT = ’ || 
confDataRecord.ALIGNMENT_TIMEUNIT) ; 


Gl 
~~ 
x 


eal 
ll 
x 


DBMS_OUTPUT.PUT_LINE (’LOG_TIME_PERIODUNIT = ’ || 
confDataRecord.LOG_TIME_ PERIODUNIT) ; 

DBMS_OUTPUT.PUT_LINE (’SAMPLE_INTERVALUNIT = ’ || 
confDataRecord.SAMPLE_INTERVALUNIT) ; 


ira) 


DBMS_OUTPUT.PUT_LINE (’ SAMPLE_BLOCKING_RATEUNIT = ’ || 
confDataRecord.SAMPLE BLOCKING_RATEUNIT) ; 
DBMS_OUTPUT.PUT_LINE (’ STORAGE_INTERVALUNIT = ’ || 
confDataRecord.STORAGE_INTERVALUNIT) ; 
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3.8 Basic Services Package 


3.8.1 General 


All Basic Service functions described in this chapter are collected in a package called GT. 
3.8.2 Miscellaneous Functions 


3.8.2.1 Overview 


Miscellaneous Functions 


timeStampToDate Converts seconds since January 1 1970 to Oracle DATE format 


dateToTimeStamp Converts DATE format to seconds since January 1 1970 


3.8.2.2 timeStampToDate 


This service converts seconds since January 1 1970 to Oracle DATE format. 


Synopsis 
DATE timeStampToDate ( 

utcSeconds IN NUMBER) ; 
Parameters 
utcSeconds [in] seconds since | January 1970 
Description 


The timeStampToDate function converts an input of seconds since January 1 1970 to Oracle 
DATE data type. 


Return Values 


Seconds converted to DATE format 


Example 


DBMS_OUTPUT.PUT_LINE(‘-> DATE : * || 
TO_CHAR (GT .timeStampToDate (log.seconds), 


*YYYY-MM-DD HH24:MI:SS’) 
‘.’ || log.microSeconds) ; 
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3.8.2.3 dateToTimeStamp 


This service converts Oracle DATE format to seconds since January | 1970. 


Synopsis 
NUMBER dateToTimeStamp ( 
time IN DATE) ; 
Parameters 
time [in] time in DATE format 
Description 


The dateToTimeStamp function converts time in Oracle DATE format to seconds since 
January | 1970. 


Return Values 


Seconds since January 1 1970. 


Example 


DBMS_OUTPUT.PUT_LINE (‘Seconds since 1970 : * | 
GT .dateToTimeStamp (SYSDATE 


Pl.— 
~ 


3.8.3 Type Directory Functions 


3.8.3.1 Overview 


Type Directory Services 


resolveObject Resolve an object instance 

objectTypeAttributes Get object type attributes from the object type directory 
objectTypeOperations Get operations for object type from the object type directory 
objectTypeEvents Get events for object type from the object type directory 
dataTypeElements Get information on elements from the object type directory 
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3.8.3.2 resolveObject 


This service resolves an object instance in the core system. 


Synopsis 
NUMBER resolveObject ( 
objectName IN VARCHAR2, 
objectType IN OUT VARCHAR2, 
accessStatus OUT GT .AccessStatus) ; 
Parameters 
objectName [in] name of the object instance to resolve 
objectType [in/out] object type name. If unknown - set to an empty string. 
accessStatus [out] status of the object access, 
see Section A.2.3, Object access status codes. 
Description 


The resolveObject function resolves one object instance in the core system. This function can 
be used for those object instances which require the object type as a key for object resolution to 
the core system, e.g MOD 300 TCL object instances associated with units, or if the object 
instance type is unknown. If the object type is not known, then set objectType to an empty 
string. 


Return Values 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
NO_PRIVILEGE Privilege not allowed 
ILLEGAL_TYPE Illegal object type name 
Example 


—- Resolve the SC5_2_UNIT1.IMS_BIG1 instance with help of object type 


SET SERVEROUTPUT ON 


DECLARE 
result NUMBER; 
objectType VARCHAR2 (30) := ‘TCL_AR_UNIT_VAR’; 


status GT.AccessStatus; 
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BEGIN 
result := GT.resolveObject (*‘SC5_2_UNIT1.IMS_BIG1’, 
objectType, 
status); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
END IF; 


DBMS_OUTPUT.PUT_LINE(‘*Access status codes 
DBMS_OUTPUT.PU 1INE (‘Access status flags 
END; 


status.codes); 
status.flags); 


[| 
~ || 


3.8.3.3 objectTypeAttributes 


This service returns type directory information regarding the attributes for a named object type. 


Synopsis 

NUMBER objectTypeAttributes ( 
object TypeName IN VARCHAR2, 
attributeCount OUT NUMBER, 
attributeNames OUT GT.StringArray, 
attributeSizes OUT GT.IntArray, 
attributeTypes OUT GT.IntArray, 
attributeTypeIndexes OUT GT.IntArray) ; 

Parameters 

objectTypeName [in] object type name to get attribute information for 

attributeCount [out] number of returned attributes in the attribute arrays 

attributeNames [out] array of attribute names 

attributeSizes [out] array of attribute data type sizes 

attributeTypes [out] array of attribute data type identifiers 

attribute TypeIndexes [out] array of attribute data type indexes 

Description 


The objectTypeAttributes function retrieves type directory information regarding the attributes 
for the object type specified in the objectTypeName parameter. The attributeCount parameter is 
the number of attributes for the object type and defines the size of the different output arrays. 


Return Values 


SUCCESS Successful completion 
RESOURCE_LACK Could not allocate memory 
ILLEGAL_TYPE Illegal object type name 
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Examples 


See Section 3.8.3.6, dataTypeElements. 


3.8.3.4 objectTypeOperations 


3-30 


This service returns type directory information regarding the operations for a named object type. 


Synopsis 

NUMBER objectTypeOperations ( 
object TypeName IN VARCHAR2, 
operationCount OUT NUMBER, 
operationNames OUT GT.StringArray, 
operationSizes OUT GT.IntArray, 
operationTypeIndexes OUT GT.IntArray) ; 

Parameters 

objectTypeName [in] object type name to get operation information for 

operationCount [out] number of returned operations in the operation arrays 

operationNames [out] array of operation names 

operationSizes [out] array of operation data type sizes 


operationTypelndexes [out] array of operation data type indexes 


Description 


The objectTypeOperations function retrieves type directory information regarding the 
operations for the object type specified in the objectTypeName parameter. The operationCount 
parameter is the number of operations for the object type and defines the size of the different 
output arrays. 


Return Values 


SUCCESS Successful completion 
RESOURCE_LACK Could not allocate memory 
ILLEGAL_TYPE Illegal object type name 
Example 


See Section 3.8.3.6, dataTypeElements. 
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3.8.3.5 objectTypeEvents 
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This service returns type directory information regarding the events for a named object type. 


Synopsis 

NUMBER objectTypeEvents ( 
object TypeName IN VARCHAR2, 
eventCount out NUMBER, 
eventNames OUT GT.StringArray, 
eventSizes OUT GT.IntArray, 
event TypeIndexes OUT GT.IntArray) ; 

Parameters 

objectTypeName [in] object type name to get event information for 

eventCount [out] number of returned events in the event arrays 

eventNames [out] array of event names 

eventSizes [out] array of event data type sizes 

eventTypelndexes [out] array of event data type indexes 

Description 


The objectTypeEvents function retrieves type directory information regarding the events for 
the object type specified in the objectTypeName parameter. The eventCount parameter is the 
number of events for the object type and defines the size of the different output arrays. 


Return Values 


SUCCESS Successful completion 
RESOURCE_LACK Could not allocate memory 
ILLEGAL_TYPE Illegal object type name 
Example 


See Section 3.8.3.6, dataTypeElements. 
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3.8.3.6 dataTypeElements 


This service returns type directory information regarding the elements in a constructed data type 
for a specified data type. 


Synopsis 

NUMBER dataTypeElements ( 
typeIndex IN VARCHAR2, 
elementCount OUT NUMBER, 
elementNames OUT GT.StringArray, 
elementOffsets OUT GT.IntArray, 
elementSizes OUT GT.IntArray, 
elementTypes OUT GT.IntArray, 
elementDirections OUT GT.IntArray, 
element TypeIndexes OUT GT.IntArray) ; 

Parameters 

typelndex [in] data type index for attribute, operation or event to get 

information for 

elementCount [out] number of returned elements in the element arrays 

elementNames [out] array of element names 

elementOffsets [out] array of element data offsets within data structure 

elementSizes [out] array of element data type sizes 

elementTypes [out] array of element data type identifiers 

elementDirections [out] array of element data directions 

elementTypelndexes [out] array of element data type indexes 

Description 


The dataTypeElements function retrieves type directory information regarding a constructed 
data type’s elements for a given data type index. The elementCount parameter is the number of 
elements for the data type and defines the size of the different output arrays. 


Return Values 


SUCCESS Successful completion 
RESOURCE_LACK Could not allocate memory 
ILLEGAL_TYPE Illegal object type name 
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Example 


Section 3.8.3 Type Directory Functions 


—- We want to resolve the AIC71_1 instance and print all attribute, 
-—- operation and event elements for that object 


SET SERVEROUTPUT ON 
DECLARE 
result NUMBER; 
objectType VARCHAR2 (30) ; 
status GT.AccessStatus; 
elemCount NUMBER; 
elemNames GT.StringArray; 
elemSizes GT.IntArray; 
elemTypes GT.IntArray; 
elemt TypeIndexes GT.IntArray; 
PROCEDURE printDataType (datatype NUMBER, 
typeIndex NUMBER) 
Is 
result NUMBER; 
elmidx NUMBER; 
elemCount NUMBER; 
elemNames GT.StringArray; 
elemOffsets GT.IntArray; 
elemSizes GT.IntArray; 
elemTypes GT.IntArray; 
elemDirections GT.IntArray; 
elemTypeIndexes GT.IntArray; 
BEGIN 
IF (dataType = GT.STRUCT_DATA_TYPE) OR 
(dataType = GT.UNION_DATA_TYPE) OR 
(dataType = GT.COMPOSITION_DATA_TYPE) OR 
(dataType = GT.OPERATION_TYPE) OR 
(dataType = GT.EVENT_TYPE) THEN 
result := GT.dataTypeElements (typeIndex, 
elemCount, 
elemNames, 
elemOffsets, 
elemSizes, 
elemTypes, 
elemDirections, 
elemTypelIndexes) ; 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE (‘Function error = * || result); 
RETURN; 
END IF; 
FOR elmIdx IN 1..elemCount LOOP 
—- Print element 
DBMS_OUTPUT .PUT_LINE (elemNames (elmIdx) | |’ 
‘ |elemSizes (elmIdx) ||’ e |elemTypes (elmIdx) ); 


-- Call printDat 


aType recursively until all elements 


-- in the complex data structure are printed 
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printDataType (elemTypes (elmIdx), elemTypeIndexes (elmIdx) ); 
END LOOP; 
END IF; 
END printDataType; 


BEGIN 

result := GT.resolveObject (‘AIC71_1’, objectType, status); 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
RETURN; 

END IF; 

IF status.codes != GT.OBJ_SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘*Access status codes = * | | status.codes) ; 
DBMS_OUTPUT.PUT_LINE(‘*Access status flags = * | | status.flags); 
RETURN; 

END IF; 

DBMS_OUTPUT.PUT_LINE(*AIC71_1 is of type *‘ || objectType); 

result := GT.objectTypeAttributes (objectType, 

elemCount, 
elemNames, 
elemSizes, 
elemTypes, 
elemTypelIndexes) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
RETURN; 

END IF; 


DBMS_OUTPUT.PUT_LINE (‘Attribute Size Type’); 

FOR elmIdx IN 1..elemCount LOOP 
DBMS_OUTPUT.PUT_LINE (elemNames (elmIdx) | |’ 

|elemSizes (elmIdx) ||’ 7 |elemTypes (elmIdx) ); 
printDataType(elemTypes (elmIdx), elemTypeIndexes (elmIdx) ); 

END LOOP; 


X 


result := GT.objectTypeOperations (objectType, 
elemCount, 
elemNames, 
elemSizes, 
elemTypelIndexes) ; 


IF result != GI.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
RETURN; 

END IF; 


DBMS_OUTPUT.PUT_LINE (‘Operation Size Type’); 
FOR elmiIdx IN 1..elemCount LOOP 


DBMS_OUTPUT.PUT_LINE (elemNames (elmIdx) | |’ 
” |elemSizes (elmIdx) ||’ ‘ |elemTypes (elmIdx) ); 
printDataType (GT.OPERATION_TYPE, lemTypeIndexes (elmIdx) ); 
END LOOP; 


3-34 3BSE 014 220R0001 


Advalnform® SQL*Connect® Programming User’s Guide 
Section 3.8.4 Object Access Services 


result GT .objectTypeEvents (objectType, 
elemCount, 
elemNames, 
elemSizes, 
elemTypeiIndexes) ; 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
R 


END IF; 


DBMS_OUTPUT .PUT_LINE ( ‘Event 


Size Type’); 


FOR elmIdx IN 1..elemCount LOOP 
DBMS_OUTPUT .PUT_LINE (elemNames (elmIdx) | |’ 


X 


|elemSizes(elmIdx) ||’ ° 


|elemTypes (elmIdx) ); 


printDataType (GT.EVENT_TYPE, lemTypeiIndexes (elmIdx) ); 


END; 


3.8.4 Object Access Services 


END LOOP; 


The Object Access Services makes it possible for you to program SQL applications in a similar 
way to the AdvaInform User API. See the Advalnform User API User’s Guide for a detailed 
description of for example the Do Request method. 


3.8.4.1 Overview 


Object Access Services 


createRequest 


Creates a unique identifier to identify one or many service requests. 


doRequest 


Performs requests identified by a unique identifier. 


deleteRequest 


Deletes unique identifier and all requests connected with that identifier. 


cancelRequest 


Deletes requests identified by unique identifier and object name. 


getAttributes 


Get attribute values once. 


getAttributesWithInit 


Get attribute values once with initialize operation. 


getAttributesCyclic 


Get attribute values cyclically. 


getAttrioutesCyclicWithInit 


Get attribute values cyclically with initialize operation. 


getAttributesOnEvent 


Get attribute values on specified event. 


getAttributesOnEventWithInit 


Get attribute values on specified event with initialize operation. 


getData 


Get subscription data. 


cancelSubscription 


Cancel permanent data subscriptions from one or several object instances. 
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cancelAll Cancel all data subscriptions towards object instances. 


executeOperation Execute a single operation on an object instance. 


3.8.4.2 createRequest 


This service returns a unique integer value to be used within the application. 


Synopsis 
NUMBER createRequest ( 


uniqueIdentity OUT NUMBER, 
combinedRequest IN BOOLEAN) ; 


Parameters 


uniqueldentity [out] unique integer value which identifies one or many demand 
subscriptions or operation executions. 


combinedRequest [in] If set to TRUE, you can combine getAttributes requests 
with executeOperation and getAttributes WithInit 


Description 


The createRequest function creates a unique integer value to be used. With the parameter 
combinedRequest you can decide whether you shall be able to mix getAttributes with 
executeOperation and getAttributes WithInit in the same request. The performance of the 
reading will be lower but this is partly compensated by a more effective combined execution. 


NOTE 


Requests will be saved on the RTA board and just refreshed on a doRequest call 
when the combinedRequest is set to FALSE. This means that the 
combinedRequest must be set to TRUE if input parameters should be changed 
between two doRequest calls. 


Return Values 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
ALLOCATION Could not allocate resource 
NO_PRIVILEGE Privilege not allowed 
Example 


See Section 3.8.4.3, doRequest. 
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This service performs all actions identified with the unique identity number. 


Synopsis 
Function for performing request: 


NUMBER doRequest ( 
uniquelIdentity IN NUMBER) ; 


Function that returns index to data after performed request. The data can be fetched with 
getObjectData: 


NUMBER doRequest ( 


uniqueIdentity IN NUMBER, 
rowIndexes OUT GT .RowIdArray, 
numberOfRows OUT NUMBER) ; 

Parameters 

uniqueldentity [in] unique integer value which identifies one or many demand 

subscriptions or/and operation executions 

rowIndexes [out] array of row indexes 

numberOfRows [out] number of rows in row index array returned. 

Description 


The doRequest performs the reading(s) initialized through getAttributes, 
getA ttributesWithInit and / or executes the operations initialized by executeOperation and 
getA ttributesWithInit. 


The first doRequest function is preferably used when the performance demand is low and the 
PL/SQL source should be easy to write. The second is used when high performance is required, 
it returns indexes directly to object data which is fetched with the getObjectData function. 


Return Values 


SUCCESS Successful completion 

EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ALLOCATION Could not allocate resource 
ERRONEOUS_CAPS One or more capabilities are erroneous 
REFERENCE Invalid unique identity 
NO_MATCHING_CAP All capabilities are erroneous or pending 
NO_PRIVILEGE Privilege not allowed 
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Example 1 


-- Initialize two demands, VALE and STATUS attributes from AIC71_10 and 
-- AIC71_11 object instances. Use first doRequest to fetch data. 


SET SERVEROUTPUT ON 


DECLARE 
value FLOAT; 
uniqueIdentifier NUMBER; 
status NUMBER; 
result NUMBER; 
numberOfObjects NUMBER; 
numberOfAttributes NUMBER; 
attributes GT.StringArray; 
attributeData GT.DataArray; 
objectNames GT.StringArray; 
accessStatus GT.AccessStatus; 
BEGIN 
objectNames(1) := ‘AIC71_10’; 
objectNames(2) := ‘AIC71_11’; 
numberOfObjects := 2; 
attributes (1) = ‘STATUS’; 
attributeData(1) := NULL; 
attributes (2) := ‘VALUE’; 
attributeData(2) := NULL; 
numberOfAttributes := 2; 


—- Create unique identifier 


result := GT.createRequest (uniqueIdentifier, FALSE); 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.createRequest error = * || result); 
RETURN; 

END IF; 


-—- Initiate DoRequest demands 
FOR objiIndex IN 1..numberOfObjects LOOP 
result := GT.getAttributes(‘AI’, 
objectNames (objIndex), 
attributes, 


numberOfAttributes, 
attributeData, 
uniquelIdentifier) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getAttributes error = * | | result); 
RETURN; 

END IF; 


END LOOP; 


—- Perform demands connected to unique identifier 


result := GT.doRequest (uniqueIdentifier) ; 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.doRequest error = * || result); 
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RETURN; 
END IF; 


-- Print result 


DBMS_OUTPUT.PUT_LINE(‘Nameaccess_status STATUS VALUE’); 
DBMS_OUTPUT.PUT_LINE (* rye 
FOR objiIndex IN 1..numberOfObjects LOOP 

result := GT.getAttributes(‘AI’, 


objectNames (objIndex), 
attributes, 
numberOfAttributes, 
attributeData, 
uniquelIdentifier, 
accessStatus); 


IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getAttributes error = * | | result); 
RETURN; 

END IF; 

result := GT.extractData(attributeData(1l), status); 

result := GT.extractData(attributeData(2), value); 

DBMS_OUTPUT .PUT_LINE (objectNames (objIndex) | | 


yo [| 


accessStatus.codes | | 


aa 


status | | 

, oN | | 

value); 
END LOOP; 


—- Remove object requests 
FOR objiIndex IN 1..numberOfObjects LOOP 
result := GT.cancelRequest (objectNames (objIndex), 
uniquelIdentifier) ; 
END LOOP; 


END; 


Example 2 


-- Initialize two demands, VALE and STATUS attributes from AIC71_10 and 
-- AIC71_11 object instances. Use second doRequest to fetch data. 


SET SERVEROUTPUT ON 


DECLARE 

elementData LONG; 

value FLOAT; 
uniqueIdentifier NUMBER; 
result NUMBER; 
numberOfObjects NUMBER; 
numberOfAttributes NUMBER; 
numberOfRows NUMBER; 
elementType NUMBER; 
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elementName VARCHAR2 (100); 
objectName VARCHAR2 (256) ; 
rowIndexes GT.RowIdArray; 
attributes GT.StringArray; 
attributeData GT .DataArray; 
objectNames GT.StringArray; 
accessStatus GT.AccessStatus; 
BEGIN 
objectNames (1) = *‘AIC71_10’; 
objectNames(2) := ‘AIC71_11’; 
numberOfObjects := 2; 
attributes (1) := ‘STATUS’; 
attributeData(1) := NULL; 
attributes (2) := ‘VALUE’; 
attributeData(2) := NULL; 
numberOfAttributes := 2; 


-—- Create unique identifier 


result := GT.createRequest (uniqueIdentifier, FALSE); 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.createRequest error = * || result); 
RETURN; 

END IF; 


-—- Initiate DoRequest demands 
FOR objiIndex IN 1..numberOfObjects LOOP 
result := GT.getAttributes(‘AI’, 
objectNames (objIndex), 
attributes, 


numberOfAttributes, 
attributeData, 
uniquelIdentifier) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getAttributes error = * | | result); 
RETURN; 

END IF; 

END LOOP; 


—- Perform demands connected to unique identifier 


result := GT.doRequest (uniqueIdentifier, rowIndexes, numberOfRows) ; 
IF result != GT.SUCCESS THEN 

DBMS_OUTPUT.PUT_LINE(‘GT.doRequest error = * || result); 

RETURN; 
END IF; 


-- Print result 


DBMS_OUTPUT.PUT_LINE (‘Nameaccess_status Attribute Value’); 
DBMS_OUTPUT.PUT_LINE ( * '); 
FOR objIndex IN 1..numberOfRows LOOP 
result := GT.getObjectData (rowIndexes (objIndex) , 
objectName, 
accessStatus, 
elementType, 
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elementName, 
elementData) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getObjectData error = * | | result); 
RETURN; 

END IF; 

IF elementType = GT.ATTRIBUTE THEN 
result := GT.extractData(elementData, value); 
DBMS_OUTPUT.PUT_LINE (objectName | | 


ea | 


accessStatus.codes | | 


se 


elementName | | 


\ || 


value); 


ELSE 
DBMS_OUTPUT.PUT_LINE (objectName | | 


eal 


accessStatus.codes | | 
‘UNKNOWN’ ) ; 


END IF; 
END LOOP; 


—- Delete entire DoRequest environment 
result := GT.deleteRequest (uniquelIdentifier) ; 


END; 


3.8.4.4 deleteRequest 


This service deletes all requests identified with the unique identity number. 


Synopsis 


NUMBER deleteRequest ( 
uniqueIdentity IN OUT NUMBER) ; 


Parameters 

uniqueldentity [in/out] unique integer value which identifies one or many demand 
subscriptions or operation executions. 

Description 


The deleteRequest function deletes all permanent subscriptions set up using getAttributes, 
getA ttributesWithInit and executeOperation which are identified through the identifier. 


The identifier is set to 0. 
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Return Values 


SUCCESS Successful completion 
REFERENCE Invalid unique identity 
Example 


See Section 3.8.4.3, doRequest. 


3.8.4.5 cancelRequest 


3-42 


This service deletes one or several requests identified with the unique identity number and 
object name. 


Synopsis 

NUMBER cancelRequest ( 
objectName IN VARCHAR2, 
uniquelIdentity IN NUMBER) ; 

Parameters 

objectName [in] name of object instance 

uniqueldentity [in] unique integer value which identifies one or many demand 

subscriptions or operation executions. 
Description 


The cancelRequest function deletes all permanent connections set up using getAttributes, 
getAttributesWithInit and executeOperation which are identified through the identifier and 
object name. 


Return Values 


SUCCESS Successful completion 
REFERENCE Invalid unique identity 
Example 


See Section 3.8.4.3, doRequest. 
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3.8.4.6 getAttributes 


This service reads attribute values from one object instance. 


Synopsis 
Function used for one shot demands: 


NUMBER getAttributes ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN OUT GT .DataArray 
accessStatus OUT GT.AccessStatus) ; 


Function used for initializing DoRequest demand: 


NUMBER getAttributes ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN GT .DataArray 
uniqueIdentity IN NUMBER) ; 


Function used for reading object data after doRequest call: 


NUMBER getAttributes ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData OUT GT .DataArray 
uniqueIdentity IN NUMBER, 
accessStatus OUT GT .AccessStatus) ; 

Parameters 

objectType [in] object type of the instance 

objectName [in] name of the object instance to get attribute value from 

attributes [in] array with attribute names to get values from 

attributeCount [in] number of attributes in the attributes array 

attributeData [in/out] array of string formatted attribute data 

uniqueldentity [in] unique integer value which identifies the request 

accessStatus [out] status of the object access, 


see Section A.2.3, Object access status codes. 
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Description 


The getAttributes function verifies that the requested attributes are part of the Object Type the 
object instances belongs to. 


When uniqueldentity = 0 the getAttributes function reads a number of attribute values from an 
object instance. 


If the parameter uniqueldentity is given a value > 0 the getAttributes will provide a different 
functionality. It will initialize a demand reading of attribute values but it will not perform the 
reading. See Section 3.8.4.2, createRequest. 


Object attributes, operations and events can be found in the AdvaInform Object Types 
Reference manual. 


Return Values 


SUCCESS Successful completion 

EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ERR_ATTRIB Incorrect attribute specification 
ERR_OPER Incorrect operation specification 
ERR_EVENT Incorrect event specification 
ERR_VALSIZE Incorrect attribute size specified 
ERR_OPSIZE Incorrect operation size specified 
ERR_EVSIZE Incorrect event size specified 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
REFERENCE Invalid unique identity 
ILLEGAL_TYPE Illegal object type name 
NO_PRIVILEGE Privilege not allowed 
NO_TRANSLATION Attribute, Operation or Event illegal 
NO_MATCHING_CAP All capabilities are erroneous or pending 
ERRONEOUS_CAPS One or more capabilities are erroneous 
Example 


-- Read STATUS and VALUE attribute from AIC71_10 


SET SERVEROUTPUT ON 


DECLARE 
result NUMBER; 
attValue NUMBER; 
numberOfAttributes NUMBER; 
attributes GT.StringArray; 
attributeData GT .DataArray; 
accessStatus GT.AccessStatus; 


objectName VARCHAR2 (256) := ‘*AIC71_10’; 
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BEGIN 
-- Read values of STATUS and VALUE attributes 
attributes (1) := ‘STATUS’; 
attributeData(1) := NULL; 
attributes (2) := ‘VALUE’; 
attributeData(2) := NULL; 
numberOfAttributes := 2; 


—-- Perform demand 
result := GT.getAttributes (‘AI’, 
objectName, 
attributes, 
numberOfAttributes, 
attributeData, 
accessStatus); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getAttributes error 
RETURN; 
END IF; 
IF accessStatus.codes != GT.OBJ_SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE (‘Access status codes = 
accessStatus.codes) ; 
DBMS_OUTPUT.PUT_LINE(‘*Access status flags = 
accessStatus.flags); 


RETURN; 
END IF; 


-- Print attribute values 
DBMS_OUTPUT.PUT_LINE (objectName) ; 
FOR attIndex IN 1..numberOfAttributes LOOP 


= | | result); 


ee 
al 


result := GT.extractData(attributeData(attIndex), attValue); 


IF result != GT.SUCCESS THEN 


DBMS_OUTPUT.PUT_LINE(‘GT.extractData error 


RETURN; 
END IF; 


Se viom | | attValue) ; 
END LOOP; 


END; 


Example Output 


AIC71_10 
—> STATUS = 256 
-—> VALUE = 56.89 


ae | | result); 


DBMS_OUTPUT.PUT_LINE(‘-> * || attributes(attIndex) | | 
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3.8.4.7 getAttributesWithInit 


This function reads attribute values from one object instance with an initialize operation. 


Synopsis 
Function used for one shot demands: 


NUMBER getAttributesWithInit ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN OUT GT .DataArray 
operation IN VARCHAR2, 
arguments IN OUT LONG, 
accessStatus OUT GT .AccessStatus) ; 


Function used for initializing DoRequest demand: 


NUMBER getAttributesWithInit ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN GT .DataArray 
operation IN VARCHAR2, 
arguments IN LONG, 
uniqueIdentity IN NUMBER) ; 


Function used for reading object data after doRequest call: 


NUMBER getAttributesWithInit ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData OUT GT .DataArray 
operation IN VARCHAR2, 
arguments IN OUT LONG, 
uniqueIdentity IN NUMBER, 
accessStatus OUT GT .AccessStatus) ; 

Parameters 

objectType [in] object type of the instance 

objectName [in] name of the object instance to get attribute value from 

attributes [in] array with attribute names to get values from 

attributeCount [in] number of attributes in the attributes array 

attributeData [in/out] array of string formatted attribute data 
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operation [in] 
arguments [in/out] 
uniqueldentity [in] 
accessStatus [out] 
Description 
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operation identifier 
string formatted operation argument data 
a unique integer value which identifies the request 


status of the object access, 
see Section A.2.3, Object access status codes. 


The getAttributes WithInit function does the same thing as the getAttributes function but adds 
an initialization operation. The initialization operation provides the means to send information 
to the object instance how to get the attribute values. As an example it could be used when the 
Object Type contains a large array and only a part of the array should be returned. 


When uniqueldentity = 0 the getAttributesWithInit function reads a number of attribute values 


from an object instance. 


When uniqueldentity > 0 the getAttributesWithInit function initializes a demand reading of 
attribute values with init (including the object name translations) but it will not perform the 


reading. 


The getAttributesWithInit function verifies that the requested attributes and the operation are 
part of the Object Type the object instances belongs to. 


Object attributes, operations and events can be found in the AdvaInform Object Types 


Reference manual. 


Return Values 


SUCCESS 
EXE_FAILED 
RESOURCE_LACK 
ERR_ATTRIB 
ERR_OPER 
ERR_EVENT 
ERR_VALSIZE 
ERR_OPSIZE 
ERR_EVSIZE 
ALLOCATION 
ILLEGAL_NAME 
REFERENCE 
ILLEGAL_TYPE 
NO_PRIVILEGE 
NO_TRANSLATION 
NO_MATCHING_CAP 
ERRONEOUS_CAPS 
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Successful completion 

System function has failed 

Could not allocate memory 

Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 

Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate resource 

Illegal characters in object name 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Attribute, Operation or Event illegal 
All capabilities are erroneous or pending 
One or more capabilities are erroneous 
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Example 

-- Read STATUS and VALUE attribute from AIC71_10 with an init 

—- operation. The init operation sets the VALUE attribute to 12.34. 
SET SERVEROUTPUT ON 

DECLARE 

opArg LONG; 

result NUMBER; 

attValue NUMBER; 

numberOfAttributes NUMBER; 

opStatus NUMBER; 

textIndex NUMBER; 

attributes GT.StringArray; 

attributeData GT .DataArray; 

accessStatus GT.AccessStatus; 

objectName VARCHAR2 (256) = *AIC71_10’; 

BEGIN 

—- Initialize out buffer 

opArg := NULL; 

-- Init operation will set the VALUE attribute to 12.34 

GT. buildData (GT.dcVALUE_CHANGE_DCX, opArg); -- opCode 

GT. buildData(GT.dcACT_VALUE_DCX, opArg) ; -- opProp 

GT.buildData(GT.dcPROG, opArg) ; -- typeOfReg 

GT.buildData(0, opArg); -- eventLog 

GT.buildData(0, opArg); -- dialogId 

GT. buildData(12.34, opArg); -- aValue 

GT.buildData(0, opArg); -- dValue 

GT.buildData(0, opArg); -- status 

GT.buildData(0, opArg); -- textIndex 

-—- Read values of STATUS and VALUE attributes 

attributes (1) = ‘STATUS’; 

attributeData (1) = NULL; 

attributes (2) = ‘VALUE’; 

attributeData (2) = NULL; 

numberOfAttributes := 2; 

-- Perform demand 

result := GT.getAttributesWithInit (‘AI’, 

objectName, 
attributes, 
numberOfAttributes, 
attributeData, 
‘ORDER’, 

opArg, 
accessStatus); 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getAttributes error = * | | result); 
RETURN; 

END IF; 


IF accessStatus.codes 


DBMS_OUTPUT.PUT_LI 
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GT.OBJ_SUCCESS THEN 
E (‘Access status codes 
accessStatus.codes) ; 


i | | 


N 
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DBMS_OUTPUT.PUT_LINE (‘Access status flags = * || 
accessStatus.flags); 


RETURN; 
END IF; 


—- Print operation status 
DBMS_OUTPUT .PUT_LINE (objectName) 


’ 
result := GT.extractData(opArg, 8, opStatus); 
result := GT.extractData(opArg, 9, textIndex); 
IF opStatus != 0 OR textIndex != 0 THEN 


DBMS_OUTPUT.PUT_LINE (‘Operation status = 
DBMS_OUTPUT.PUT_LINE ( ‘Text Index = 
END IF; 


opStatus); 
text Index) ; 


aed 
| 


-- Print attribute values 
FOR attIndex IN 1..numberOfAttributes LOOP 


result := GT.extractData(attributeData(attIndex), attValue); 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.extractData error = * | | result); 
RETURN; 

END IF; 

DBMS_OUTPUT.PUT_LINE(‘-> * || attributes(attIndex) | | 

Yes | | attValue) ; 
END LOOP; 
END; 


3.8.4.8 getAttributesCyclic 


This function reads attribute values from one object instance cyclically. The function creates a 
permanent subscription that exists until removed. 


Synopsis 

NUMBER getAttributesCyclic ( 
objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN GT .DataArray 
cycleTime IN DOUBLE PRECISION) ; 

Parameters 

objectType [in] object type of the instance 

objectName [in] name of the object instance to get attribute value from 

attributes [in] array with attribute names to get values from 

attributeCount [in] number of attributes in the attributes array 

attribute Data [in] array of string formatted attribute data 

cycleTime [in] time in seconds between each get of attribute values 
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Description 


The getAttributesCyclic function gets attribute values cyclically. The getAttributesCyclic 
function sets up a permanent subscription with the specified cycleTime. The data is received 
with the getData function. 


To remove the subscription the cancelSubscription function should be called!. The 
getAttributesCyclic function verifies that the requested attributes are part of the Object Type 
the object instances belong to. 


Object attributes, operations and events can be found in the AdvaInform Object Types 
Reference manual. 


Return Values 


SUCCESS Successful completion 

EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ERR_ATTRIB Incorrect attribute specification 
ERR_OPER Incorrect operation specification 
ERR_EVENT Incorrect event specification 
ERR_VALSIZE Incorrect attribute size specified 
ERR_OPSIZE Incorrect operation size specified 
ERR_EVSIZE Incorrect event size specified 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
REFERENCE Invalid unique identity 
ILLEGAL_TYPE Illegal object type name 
NO_PRIVILEGE Privilege not allowed 
NO_TRANSLATION Attribute, Operation or Event illegal 
NO_MATCHING_CAP All capabilities are erroneous or pending 
ERRONEOUS_CAPS One or more capabilities are erroneous 
Example 


—- Read STATUS and VALUE attributes from AIC71_10 and AIC71_11 object 
—- instances. Set up the reading as cyclic subscriptions with 10 and 5 
-—- seconds intervall. Wait for data in 60 seconds. 


SET SERVEROUTPUT ON 


DECLARE 

elementData LONG; 

result NUMBER; 
attValue NUMBER; 
elementType NUMBER; 
numberOfRows NUMBER; 
numberOfObjects NUMBER; 
numberOfAttributes NUMBER; 


cycleTime FLOAT; 


1. It is essential that the subscription is removed before the application terminates. 
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timeOut FLOAT; 
objectName VARCHAR2 (256) ; 
elementName VARCHAR2 (100) ; 
rowIndexes GT.RowIdArray; 
attributeData GT.DataArray; 
attributes GT.StringArray; 
objectNames GT.StringArray; 
accessStatus GT.AccessStatus; 
EGIN 
objectNames(1) := ‘AIC71_10’; 
objectNames(2) := ‘AIC71_11’; 
numberOfObjects := 2; 
attributes (1) := ‘STATUS’; 
attributeData(1) := NULL; 
attributes (2) := ‘VALUE’; 
attributeData(2) := NULL; 
numberOfAttributes := 2; 
cycleTime := 10.0; 


-—- Initiate subscriptions 
FOR objiIndex IN 1..numberOfObjects LOOP 
result := GT.getAttributesCyclic(‘AI’, 
objectNames (objIndex) 
attributes, 


numberOfAttributes, 
attributeData, 
cycleTime) ; 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE (‘*GT.getAttributesCyclic error 
result); 
RETURN; 
END IF; 


END LOOP; 


-- Wait for data in 60 seconds 
timeOut := 60.0; 
WHILE timeOut > 0 LOOP 


, 


as || 


result := GT.getData(timeOut, rowIndexes, numberOfRows) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getData error = * || result); 
RETURN; 

END IF; 


FOR idx IN 1..numberOfRows LOOP 


result := GT.getObjectData (rowIndexes (idx), 
objectName, 
accessStatus, 
elementType, 
elementName, 
elementData); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getObjectData error = * | | result); 
RETURN; 
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END IF; 


DBMS_OUTPUT .PUT_LINE (objectName) ; 
IF accessStatus.codes != GT.OBJ_SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Access status codes = * | | 
accessStatus.codes) ; 
DBMS_OUTPUT.PU ,INE(*‘Access status flags = * | | 
accessStatus.flags); 


RETURN; 
END IF; 


IF elementType = GT.ATTRIBUTE THEN 
-- Print attribute value 


result := GT.extractData(elementData, attValue); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.extractData error = * | | result); 
RETURN; 
END IF; 
DBMS_OUTPUT.PUT_LINE(*-> * || elementName | | 
oa | | attValue) ; 
END IF; 
END LOOP; 
END LOOP; 
result := GT.cancelAll; 


END; 


3.8.4.9 getAttributesCyclicWithinit 


The function performs an initialization and then gets attribute values cyclically from one object 
instance. The subscription is permanent and exists until it is removed. 


Synopsis 

NUMBER getAttributesCyclicWithInit ( 
objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN GT .DataArray 
cycleTime IN DOUBLE PRECISION, 
operation IN VARCHAR2, 
arguments IN LONG, 
accessStatus OUT GT .AccessStatus) ; 

Parameters 

objectType [in] object type of the instance 

objectName [in] name of the object instance to get attribute value from 

attributes [in] array with attribute names to get values from 

attributeCount [in] number of attributes in the attributes array 


3-52 3BSE 014 220R0001 


attributeData 
cycleTime 
operation 
arguments 


accessStatus 


Description 


[in] 
[in] 
[in] 
[in] 


[out] 
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array of string formatted attribute data 

time in seconds between each get of attribute values 
operation name 

string formatted operation argument data 


status of the object access, 
see Section A.2.3, Object access status codes. 


The getAttributesCyclicWithInit function is the same as the getAttributesCyclic function, 
but adds an initialization operation. The initialization operation provides the means to send 
information to the object instance how to get the attribute values. 


The getAttributesCyclicWithInit function verifies that the requested attributes and the 
operation are part of the Object Type the object instances belongs to. 


Object attributes, operations and events can be found in the AdvaInform Object Types 


Reference manual. 


Return Values 


SUCCESS 
EXE_FAILED 
RESOURCE_LACK 
ERR_ATTRIB 
ERR_OPER 
ERR_EVENT 
ERR_VALSIZE 
ERR_OPSIZE 
ERR_EVSIZE 
ALLOCATION 
ILLEGAL_NAME 
REFERENCE 
ILLEGAL_TYPE 
NO_PRIVILEGE 


NO_TRANSLATION 
NO_MATCHING_CAP 
ERRONEOUS_CAPS 


Example 


Successful completion 

System function has failed 

Could not allocate memory 

Incorrect attribute specification 
Incorrect operation specification 
Incorrect event specification 

Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate resource 

Illegal characters in object name 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Attribute, Operation or Event illegal 
All capabilities are erroneous or pending 
One or more capabilities are erroneous 


See Section 3.8.4.7, getAttributesWithInit and Section 3.8.4.8, getAttributesCyclic. 
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3.8.4.10 getAttributesOnEvent 


This function reads attribute values from one object instance when a specific event is detected in 
the objects. The function creates a permanent subscription that persists until removed. 


Synopsis 

NUMBER getAttributesOnEvent ( 
objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN GT.DataArray 
event IN VARCHARZ2) ; 

Parameters 

objectType [in] object type of the instance 

objectName [in] name of the object instance to get attribute value from 

attributes [in] array with attribute names to get values from 

attributeCount [in] number of attributes in the attributes array 

attributeData [in] array of string formatted attribute data 

event [in] event name 

Description 


The getAttributesOnEvent function gets attribute values and event data on event. On event 
means that when the object instance detects the event, data is sent to the subscriber. 


The getAttributesOnEvent function sets up a permanent subscription on the event. The data is 
received with the getData function. 


To remove the subscription the cancelSubscription function should be called. It is essential that 
the subscription is removed before the application terminates. 


The getAttributesOnEvent function verifies that the requested attributes and event are part of 
the Object Type the object instance belong to. 


Object attributes, operations and events can be found in the AdvaInform Object Types 
Reference manual. 


Return Values 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ERR_ATTRIB Incorrect attribute specification 
ERR_OPER Incorrect operation specification 
ERR_ EVENT Incorrect event specification 
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ERR_VALSIZE 
ERR_OPSIZE 
ERR_EVSIZE 
ALLOCATION 
ILLEGAL_NAME 
REFERENCE 
ILLEGAL_TYPE 
NO_PRIVILEGE 
NO_TRANSLATION 
NO_MATCHING_CAP 
ERRONEOUS_CAPS 


Example 


-- Read STATUS and VALU 


-—- instances. 
-—- data in 60 seconds. 


f 


EF attributes from AIC71_10 
Set up the reading as subscriptions 
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Incorrect attribute size specified 
Incorrect operation size specified 
Incorrect event size specified 

Could not allocate resource 

Illegal characters in object name 
Invalid unique identity 

Illegal object type name 

Privilege not allowed 

Attribute, Operation or Event illegal 
All capabilities are erroneous or pending 
One or more capabilities are erroneous 


and AIC71_11 object 
on event. Wait for 


SET SERVEROUTPUT ON 

DECLARE 
elementData LONG; 
result NUMBER; 
attValue NUMBER; 
elementType NUMBER; 
numberOfRows NUMBER; 
numberOfObjects NUMBER; 
numberOfAttributes NUMBER; 
timeOut FLOAT; 
event VARCHAR2 (30); 
objectName VARCHAR2 (256) ; 
elementName VARCHAR2 (100); 
rowIndexes GT.RowIdArray; 
attributeData GT.DataArray; 
attributes GT.StringArray; 
objectNames GT.StringArray; 
accessStatus GT .AccessStatus; 

BEGIN 


objectNames (1) 
objectNames (2) 
numberOfObjects := 2; 


‘AIC71_10'; 
ATCT L112"; 


attributes (1) = ‘STATUS’; 
attributeData(1) := NULL; 
attributes (2) := ‘VALUE’; 
attributeData(2) := NULL; 
numberOfAttributes := 2; 


event := ‘EVENT’; 
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—- Initiate subscriptions 
FOR objiIndex IN 1..numberOfObjects LOOP 


result := GT.getAttributesOnEvent (‘AI’, 
objectNames (objIndex), 
attributes, 
numberOfAttributes, 
attributeData, 
event); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getAttributesOnEvent error = °* || 
result); 
RETURN; 
END IF; 


END LOOP; 


-- Wait for data in 60 seconds 


timeOut := 60.0; 
WHILE timeOut > 0 LOOP 
result := GT.getData(timeOut, rowIndexes, numberOfRows) ; 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getData error = * || result); 
RETURN; 
END IF; 


FOR idx IN 1..numberOfRows LOOP 


result := GT.getObjectData (rowIndexes (idx), 
objectName, 
accessStatus, 
elementType, 
elementName, 
elementData) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getObjectData error = * | | result); 
RETURN; 

END IF; 


DBMS_OUTPUT .PUT_LINE (objectName) ; 

IF accessStatus.codes != GT.OBJ_SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Access status codes = * | | 
accessStatus.codes) ; 
DBMS_OUTPUT.PUT_LINE(‘*Access status flags = * | | 
accessStatus.flags); 


RETURN; 
END IF; 


IF elementType = GT.ATTRIBUTE THEN 
-- Print attribute value 


result := GT.extractData(elementData, attValue); 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.extractData error = * | | result); 
RETURN; 

END IF; 

DBMS_OUTPUT.PUT_LINE(*-> * || elementName | | 

ee eae 


attValue) ; 
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END IF; 
END LOOP; 
END LOOP; 


FOR objiIndex IN 1..numberOfObjects LOOP 
result := GT.cancelSubscription (objectNames (objIndex) ); 
END LOOP; 


END; 


3.8.4.11 getAttributesOnEventWithInit 


This function gets attribute values and event data on event with an initialize operation. The 
function creates a permanent subscription that will persist until it is removed. 


Synopsis 

NUMBER getAttributesOnEventWithInit ( 
objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
attributes IN GT.StringArray, 
attributeCount IN NUMBER, 
attributeData IN GT .DataArray 
event IN VARCHAR2, 
operation IN VARCHAR2, 
arguments IN LONG, 
accessStatus OUT GT .AccessStatus) ; 

Parameters 

objectType [in] object type of the instance 

objectName [in] name of the object instance to get attribute value from 

attributes [in] array with attribute names to get values from 

attributeCount [in] number of attributes in the attributes array 

attribute Data [in] array of string formatted attribute data 

event [in] event name 

operation [in] operation name 

arguments [in] string formatted operation argument data 

accessStatus [out] status of the object access, 

see Section A.2.3, Object access status codes. 
Description 


The getAttributesOnEventWithInit function is the same as the getAttributesOnEvent 
function, but adds an initialization operation. The initialization operation provides the means to 
send information to the object instance how to get the attribute values. 
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Object attributes, operations and events can be found in the AdvaInform Object Types 
Reference manual. 


Return Values 


SUCCESS Successful completion 

EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ERR_ATTRIB Incorrect attribute specification 
ERR_OPER Incorrect operation specification 
ERR_EVENT Incorrect event specification 
ERR_VALSIZE Incorrect attribute size specified 
ERR_OPSIZE Incorrect operation size specified 
ERR_EVSIZE Incorrect event size specified 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
REFERENCE Invalid unique identity 
ILLEGAL_TYPE Illegal object type name 
NO_PRIVILEGE Privilege not allowed 
NO_TRANSLATION Attribute, Operation or Event illegal 
NO_MATCHING_CAP All capabilities are erroneous or pending 
ERRONEOUS_CAPS One or more capabilities are erroneous 
Example 


See Section 3.8.4.7, getAttributesWithInit and Section 3.8.6.5, buildData. 


3.8.4.12 getData 


The function gets the data that has been subscribed. 


Synopsis 

NUMBER getData ( 
timeOut IN OUT DOUBLE PRECISION, 
rowIndexes OUT GT .RowIdArray, 
numberOfRows OUT NUMBER) ; 

Parameters 

time Out [in] time to receive data (unit seconds) 

rowIndexes [out] array of row indexes 

numberOfRows [out] number of returned rows in row index array 
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Description 


The getData function returns at time out or when data from previously requested permanent 
subscriptions have been received. Permanent subscription are set up with the 
getAttributesOnEvent, getAttributesCyclic, getAttributesOnEventWithInit and 
getAttributesCyclicWithInit functions. The row/ndexes are row identities that are used with 
the getObjectData function to get the actual data received. 


The getData must be called by the user until the time is zero. 


Any data received between getData calls will be queued up. When you call getData again, they 
will immediately be returned. The queues for each attribute has 20 positions, the same applies 
whether it is a cyclic or an event subscription. If you do not call getData in time, and the queues 
are filled up, the oldest data will be lost. Overflow will, as all other data loss, be indicated by the 
object status flag set to GT.OBJ_DATA_LOST. When you call getData again the first received 
event will hold the oldest data (still in the queue) and loss of data will be indicated through the 
object status flags. After this the events will arrive in the order data was queued. 


Return value 


SUCCESS Successful completion 
EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
NO_ASSOCIATION No subscriptions active 
ERR_TIMEOUT Time Out out of range 
Example 


See Section 3.8.4.8, getAttributesCyclic. 


3.8.4.13 cancelSubscription 


The function cancels all subscriptions towards one object instance. 


Synopsis 
NUMBER cancelSubscription ( 

objectName IN VARCHAR2) ; 
Parameters 
objectName [in] name of the object instance to cancel subscriptions from 
Description 


The cancelSubscription function removes all previously requested permanent subscriptions 
from one object instance. Permanent subscription are set up with the getAttributesOnEvent, 
getAttributesCyclic, getAttributesOnEventWithInit, and getAttributesCyclicWithInit 
functions. 
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Return Values 
SUCCESS Successful completion 


Example 


See Section 3.8.4.8, getAttributesCyclic. 


3.8.4.14 cancelAll 
The functions remove all subscriptions towards all object instances the program/task has 
initiated. 
Synopsis 


NUMBER cancelAl1l1; 


Parameters 


None 


Description 


The cancelAll function removes all previously requested permanent subscriptions. Permanent 
subscription are set up with the getAttributesOnEvent, getAttributesCyclic, 
getAttributesOnEventWithInit, and getAttributesCyclicWithInit functions. 


Return Value 
SUCCESS Successful completion 


Example 


See Section 3.8.4.9, getAttributesCyclicWithInit. 
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3.8.4.15 executeOperation 


The purpose of this function is to execute an operation in one object instance. Operations are the 
only way to update values in object instances. Which operations you can use per object type, 
and the attributes they change, can be found in the AdvaInform Object Types Reference manual. 
See the Commands part for each object type. 


Synopsis 
Function used for single executions: 


NUMBER executeOperation ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
operation IN VARCHAR2, 
arguments IN OUT LONG, 
accessStatus OUT GT .AccessStatus) ; 


Function used for initializing Do-Request demand: 


NUMBER executeOperation ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
operation IN VARCHAR2, 
arguments IN LONG, 
uniqueIdentity IN NUMBER) ; 


Function used for reading object data after doRequest call: 


NUMBER executeOperation ( 


objectType IN VARCHAR2, 
objectName IN VARCHAR2, 
operation IN VARCHAR2, 
arguments IN OUT LONG, 
uniqueIdentity IN NUMBER, 
accessStatus OUT GT .AccessStatus) ; 

Parameters 

objectType [in] object type of the instance 

objectName [in] name of the object instance 

operation [in] operation name 

arguments [in/out] operation argument data 

accessStatus [out] status of the object access, 

see Section A.2.3, Object access status codes. 
uniqueldentity [in] a unique integer value which identifies the request 
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Description 


The executeOperation function verifies that the operation is part of the Object Type the object 
instance belongs to. 


Object attributes, operations and events can be found in the AdvaInform Object Types 
Reference manual. 


Return Value 


SUCCESS Successful completion 

EXE_FAILED System function has failed 
RESOURCE_LACK Could not allocate memory 
ERR_ATTRIB Incorrect attribute specification 
ERR_OPER Incorrect operation specification 

ERR_ EVENT Incorrect event specification 
ERR_VALSIZE Incorrect attribute size specified 
ERR_OPSIZE Incorrect operation size specified 
ERR_EVSIZE Incorrect event size specified 
ALLOCATION Could not allocate resource 
ILLEGAL_NAME Illegal characters in object name 
REFERENCE Invalid unique identity 
ILLEGAL_TYPE Illegal object type name 
NO_PRIVILEGE Privilege not allowed 
NO_TRANSLATION Attribute, Operation or Event illegal 
NO_MATCHING_CAP All capabilities are erroneous or pending 
ERRONEOUS_CAPS One or more capabilities are erroneous 
Example 


-- executeOperationExample.sql 


-- Set the VALUE attribute of AIC71_10 instance to 12.34 


SET SERVEROUTPUT ON 


DECLARE 
opArg LONG; 
result NUMBER; 
accessStatus GT .AccessStatus; 
objectName VARCHAR2 (256); 
BEGIN 
objectName := ‘AIC71_10’; 


-—- Initialize out buffer 
opArg := NULL; 
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-- Initialize operation data 


GT. buildData (GT.dcVALUE_CHANGE_DCX, opArg); opCode 
GT. buildData(GT.dcACT_VALUE_DCX, opArg) ; opProp 
GT.buildData(GT.dcPROG, opArg) ; typeOfReq 
GT.buildData(0, opArg); eventLog 
GT.buildData(0, opArg); dialogIid 
GT. buildData(12.34, opArg); aValue 
GT.buildData(0, opArg); dValue 
GT.buildData(0, opArg); status 
GT.buildData(0, opArg); text Index 
-- Perform demand 

result := GT.executeOperation (‘AI’, 

objectName, 
‘ORDER’, 
opArg, 
accessStatus) ; 

IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.executeOperation error = * | | result); 
RETURN; 

END IF; 


—- Print object access status 


DBMS_OUTPUT .PU IN 


E (‘Access status codes 


accessStatus.codes) ; 


DBMS_OUTPUT .PU IN 


E (‘Access status flags 


END; 


Example Output 


Access status codes 
Access status flags 


3.8.5 Basic Support Functions 


3.8.5.1 Overview 


Basic Support Services 


accessStatus.flags) ; 


getLocalNode 


Retrieve current network and node id 
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3.8.5.2 getLocalNode 


This service retrieves the network and node id. 


Synopsis 
NUMBER getLocalNode ( 
network out 
node OUT 
Parameters 
network [out] network id 
node [out] node id 
Description 


NUMBER, 
NUMBER) ; 


The getLocalNode function retrieves the network and node id for the station where Connect 


server is located. 


Return Values 


SUCCESS Successful completion 
Example 
SET SERVEROUTPUT ON 
DECLARE 
network NUMBER; 
node NUMBER; 
BEGIN 
result := GT.getLocalNode (network, node); 
DBMS_OUTPUT.PUT_LINE (‘Network = * || network); 
DBMS_OUTPUT.PUT_LINE (‘Node = * || node); 
END; 
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3.8.6 Object Data Functions 


3.8.6.1 General Data Format 


All in and output data must be converted to Oracle LONG data type. 


Syntax 
° Strings are always surrounded by quotas. 


Datatypes with several elements like structures, open arrays, must be converted to LONG 
data type and separated with commas. 


° Data always ended with a comma. 


Examples 


1. Assume that we have a structure: 


TYPE AI_comp_1 IS RECORD 


STATUS NUMBER; 
VALUE FLOAT; 
NO_OF_DEC NUMBER; 


where 


STATUS = 10 
VALUE = 56.78 
NO_OF_DEC = 3 


This is converted to an Oracle LONG type as: 


DATA = 10,56.78,3, 


Fl’ 


STATUS VALUE NO_OF_DEC 


2. A structure in a structure like: 


TYPE HsAttribute IS RECORD 
attributeID NUMBER; 
status NUMBER; 
value LONG; 


i 
TYPE HsAttributeType IS RECORD 


max_is NUMBER; 
last_is NUMBER; 
array HsAttribute (50); 
\; 
where 
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array(1l).attributeID = 7 
array(1l).status = 123 
array(1l).value = ‘900’ 
array(2).attributeID = 8 
array(2).status = 67 
array (2).value = ‘400’ 
max_is = 50 

last_is = 2 


This is converted to an Oracle LONG type as: 
DATA = 50,2,7,123,7900",8,67,"400", 


Loahfennna 


max_is,array(1).atfributeID array 
last_is array(1l).status array(1).value array(2).status 


-attribuxeID array(2) -value 


3.8.6.2 Overview 


Object Data Functions 


getObjectData Get object data for one row index 
extractData Extract one element from LONG format data 
buildData Add one element to LONG format data 


3.8.6.3 getObjectData 


Translate row index into object data. 


Synopsis 

NUMBER getObjectData ( 
rowIndex IN ROWID, 
objectName OUT VARCHAR2, 
accessStatus OUT GT .AccessStatus, 
elementType OUT NUMBER, 
elementName OUT VARCHAR2, 
elementData OUT LONG) ; 

Parameters 

rowIndex [in] row index 

objectName [out] name of the object instance 
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accessStatus [out] status of the object access, 
see Section A.2.3, Object access status codes. 


elementType [out] element type, GT.ATTRIBUTE, GT.OPERATION or 
GT.EVENT 

elementName [out] element name 

elementData [out] string formatted element data 

Description 


The getObjectData function translates a row index into object data. The elementData is always 
formatted as a string, see Section 3.8.6.1, General Data Format. 


Return Value 


SUCCESS Successful completion 
ILLEGAL_ROWID Row ID illegal 
Example 


See Section 3.8.6.5, buildData. 


Extract one data element from string formatted data. 


Synopsis 
Extract first element as NUMBER and return rest of string: 


NUMBER extractData ( 
inData IN OUT LONG, 
numberData OUT NUMBER) ; 


Extract first element as BOOLEAN and return rest of string: 


NUMBER extractData ( 
inData IN OUT LONG, 
boolData OUT BOOLEAN) ; 


Extract first element as VARCHAR? and return rest of string: 


NUMBER extractData ( 
inData IN OUT LONG, 
stringData OUT VARCHAR2) ; 


Extract NUMBER element with index as key. Input string is not changed: 


NUMBER extractData ( 


inData IN LONG, 
element Index IN NUMBER, 
numberData OUT NUMBER) ; 
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Extract BOOLEAN element with index as key. Input string is not changed: 


NUMBER extractData ( 


inData IN LONG, 
element Index IN NUMBER, 
boolData OUT BOOLEAN) ; 


Extract VARCHAR2 element with index as key. Input string is not changed: 


NUMBER extractData ( 


inData IN LONG, 
element Index IN NUMBER, 
stringData OUT VARCHAR2) ; 

Parameters 

inData [in/out] string formatted data 

elementIndex [in] element index in string formatted data 

numberData [out] NUMBER data type element 

boolData [out] BOOLEAN data type element 

stringData [out] VARCHAR? data type element 

Description 


The extractData function parses a string formatted data and translates the first element into 
NUMBER, BOOLEAN or VARCHAR? data. The inData is always formatted as a string, see 
Section 3.8.6.1, General Data Format. 


Return Value 


SUCCESS Successful completion 
ILLEGAL_TYPE Incorrect data type 
EMPTY_BUFFER No more data in string 
Example 


See Section 3.8.6.5, buildData. 


3.8.6.5 buildData 


Append one data element to the end of a string formatted data. 


Synopsis 
Add NUMBER element to string: 


buildData ( 
numberData IN NUMBER, 
outData IN OUT LONG) ; 
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Add BOOLEAN element to string: 


buildData ( 
boolData IN BOOLEAN, 
outData IN OUT LONG) ; 


Add VARCHAR? element to string: 


buildData ( 
stringData IN VARCHAR2, 
outData IN OUT LONG) ; 

Parameters 

numberData [in] NUMBER data type element 

stringData [in] VARCHAR? data type element 

outData [in/out] string formatted data 

Description 


The buildData procedure translates NUMBER, BOOLEAN or VARCHAR? element into string 
and adds it to a string formatted data. The outData is always formatted as a string, see Section 
3.8.6.1, General Data Format. The outData buffer should always be set to NULL before 
building, otherwise the result is undefined. 


Return Value 


None. 


Example 
-- Read log entrys from History numerical log 


SET SERVEROUTPUT ON 


DECLARE 
TYPE TimeStamp IS RECORD ( 
seconds NUMBER, 
microSeconds NUMBER) ; 


TYPE LogData IS RECORD ( 


utc TimeStamp, 
entryValue FLOAT, 
entryStatus NUMBER, 
accessStatus NUMBER) ; 

TYPE NUMERIC_ENTRY_UT IS RECORD ( 
max_is NUMBER, 
last_is NUMBER, 
seconds GT.IntArray, 
microSeconds GT.IntArray, 
entryValue GT.IntArray, 


3BSE 014 220R0001 


3-69 


Advalnform® SQL*Connect® Programming User’s Guide 
Chapter 3 Advalinform SQL *Connect Programming 


3-70 


entryStatus 
accessStatus 


data 
result 
attValue 


numberOfObjects 
numberOfAttributes 


timeOut 
attributes 
objectNames 
accessStatus 
operation 
event 
logName 
objectName 
objectType 
elementType 
elementName 
elementData 
rowIndexes 
numberOfRows 
arguments 


attributeData 


received 
log 


GT 
GT 


-IntArray, 
-IntArray); 


LONG; 


y2ZaZzZez 


VA 
VA 


-—- History constants 


SECONDS 
MINUTES 


hsSTAR IME 
hsEND_TIME 
hsFROM_START 


hsPRESEN 
hsLOCAL 
hsUTC 


hsRAW 


hsINTERPOLA 


hsINTERPOLA 


hsTREND 


hsSECONDARY_ 


hsDISPLAY 


hsNO_OF_RTRV_TYPI 


hsAVG 
hsMAX 
hsMIN 
hsINST 


UMBI 
UMBI 
UMBI 
UMBI 
LOAT; 
GT.StringArray; 

GT.StringArray; 

GT.AccessStatus; 


LON 


ae 


AeA 
ve) 
s 


= 


zi 


RCHAR2 (30); 
RCHAR2 (30); 
RCHAR2 (256); 
RCHAR2 (256); 
RCHAR2 (256) 
BER; 

RCHAR2 (100); 
G 

R 


, 


, 


owldArray; 


NUMBER; 
LONG; 
GT. 


DataArray; 
-IntArray; 


NUMERIC_ENTRY_UT; 


CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 
CONSTANT NUMBE 


AHDDD 


AAA HA ADD 


AHA DA 
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hsASCENDING CONSTANT NUMBER := 0; 

hsDESCENDING CONSTANT NUMBER := 1; 

hsFORWARD CONSTANT NUMBER := 0; 

hsBACKWARD CONSTANT NUMBER := 1; 

hsCURRENT CONSTANT NUMBER := 0; 

hsORIGINAL CONSTANT NUMBE = H 

hsAVERAGE CONSTANT NUMBER := 0; 

hsMAX IMUM CONSTANT NUMBER := 1; 

hsMINIMUM CONSTANT NUMBER := 2; 

hsINSTANTANEOUS CONSTANT NUMBER := 3; 

hsSUM CONSTANT NUMBER := 4; 

hsSUM_OF_SQRS CONSTANT NUMBER := 5; 

hsSTANDARD_DEV CONSTANT NUMBER := 6; 

hsNUM_OF_VALUES CONSTANT NUMBER := 7; 

hsWILDCARD CONSTANT NUMBER := 8; 
BEGIN 

DBMS_OUTPUT .ENABLE (10000); 

objectName := ‘LOG MANAGER’ ; 

objectType := ‘LogMgr’; 

logName := ‘OBA73_1’'; 

attributes (1) := ‘NUMERIC_ENTRY_UT’; 

attributes (2) := ‘NUMERIC_PRES_ATTR’; 

numberOfAttributes sS2's 

event := ‘DataAvailable’; 

operation := ‘GetNumeric’; 

-- Initialize out buffers 

arguments := NULL; 

attributeData (1) = NULL; 

attributeData (2) = NULL; 

-- Initialize operation data 

—- objectName 

result := GT.buildData(logName, arguments) ; 

-—- selectionTime.seconds 

result := GT.buildData(0, arguments) ; 

—- selectionTime.microSeconds 

result := GT.buildData(0, arguments) ; 

—- timeJustification 

result := GT.buildData (hsEND_TIME, arguments) ; 

-- timeType 

result := GT.buildData(hsPRESENT, arguments) ; 
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-- timeInterv.unit 

result := GT.buildData (MINUTES, arguments) ; 
—- timeInterv.pad 

result := GT.buildData(0, arguments) ; 

-—- timeInterv.value 

result := GT.buildData(60, arguments) ; 


-- cyclicTimeInterv.unit 

result := GT.buildData (SECONDS, arguments) ; 
-—- cyclicTimeInterv.pad 

result := GT.buildData(0, arguments) ; 

-- cyclicTimeInterv.value 

result := GT.buildData(0, arguments) ; 


-- initialValueEntries 
result := GT.buildData(400, arguments) ; 


-- initialEventEntries 
result := GT.buildData(0, arguments) ; 


-- cyclicValueEntries 
result := GT.buildData(0, arguments) ; 


-—- cyclicEventEntries 


result := GT.buildData(0, arguments) ; 

-- retrievalType 

result := GT.buildData(hsRAW, arguments) ; 

-- interpolationAlg 

result := GT.buildData(hsINST, arguments) ; 

-- logEntryOrder 

result := GT.buildData (hsASCENDING, arguments) ; 


—- directionOfRequest 


result := GT.buildData (hsFORWARD, arguments) ; 
-- dataSelector 

result := GT.buildData (hsCURRENT, arguments) ; 
== querystart 

result := GT.buildData (hsWILDCARD, arguments) ; 
-—- accessID 

result := GT.buildData(0, arguments) ; 


-- Initialize attribute data 


-—- NUMERIC_ENTRY_UT.max_is 
result := GT.buildData(499, attributeData (1) ); 
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—- NUMERIC_ENTRY_UT.last_is 


result := GT.buildData (GT.OPEN_ARRAY_IS_EMPTY, attributeData (1) ); 


-- Initiate subscription 


result := GT.getAttributesOnEventWithInit (objectType, 
objectName, 
attributes, 
numberOfAttributes, 


attributeData, 


event, 
operation, 
arguments, 


accessStatus); 


IF result != GT.SUCC 


ESS THEN 


DBMS_OUTPUT.PUT_LIN 


RETURN; 
END IF; 


result); 


-- Wait for data in 20 seconds 


timeOut := 20.0; 
received(1l 
received(2) := 


) = 0; 
0; 


WHILE timeOut > 0 LOOP 


result := GT.getData(timeOut, rowIndexes, numberOfRows) ; 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getData error = * || result); 
RETURN; 
END IF; 
FOR idx IN 1..numberOfRows LOOP 
result := GT.getObjectData (rowIndexes (idx), 
objectName, 
accessStatus, 
elementType, 
elementName, 


elementData) ; 


E(*‘GT.getAttributesOnEventWithInit error 
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IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.getObjectData error = * | | result); 
RETURN; 

END IF; 

IF accessStatus.codes != GT.OBJ_SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Access status codes = * | | 

accessStatus.codes) ; 
DBMS_OUTPUT.PUT_LINE(‘*Access status flags = * | | 

accessStatus.flags); 
RETURN; 

END IF; 
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IF elementType = GT.ATTRIBUTE THEN 


IF elementName = ‘NUMERIC_ENTRY_UT’ THEN 
attributeData(1) := elementData; 
received(1) := 1; 

ELSE 


attributeData(2) := elementData; 
received(2) := 1; 


END IF; 
END IF; 
IF received(1) = 1 AND received(2) = 1 THEN 
timeOut := 0; 
END IF; 
END LOOP; 
END LOOP; 
IF received(1) = 1 AND received(2) = 1 THEN 
-- Print attribute value 
result := GT.extractData(attributeData(1), log.max_is) ; 
result := GT.extractData(attributeData(1), log.last_is) ; 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘GT.extractData error = * || result); 
RETURN; 
END IF; 
FOR idx IN 1..log.last_is LOOP 
result := GT.extractData(attributeData(1), log.seconds (idx) ) ; 
result := GT.extractData (attributeData(1), 
log.microSeconds (idx) ); 
result := GT.extractData (attributeData(1), 
log.entryValue (idx) ); 
result := GT.extractData (attributeData(1), 
log.entryStatus (idx) ); 
result := GT.extractData (attributeData(1), 


log.accessStatus (idx) ); 
DBMS_OUTPUT.PUT_LINE(‘*-> DATA# ‘||idx||”’ : @ * || 
TO_CHAR (GT. timeStampToDate (log. seconds (idx) +2*60*60), 
‘YYYY-MM-DD HH24:MI:ss’) || 
‘eit | log.microSeconds (idx) | | 
|log.entryValue (idx) | | 
* Status: * | | 
log.entryStatus (idx) ); 
END LOOP; 
ELSE 
DBMS_OUTPUT.PUT_LINE(*> History data @ * || 
SYSDATE | | 
‘ from * | | 
logName | | 
‘ WAS NOT RECEIVED !’); 
END: TF} 
result := GT.cancelAll1; 


am 


END; 
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Chapter 4 Maintenance & Troubleshooting 


4.1 Preventive Maintenance 


4.1.1 General 


Refer to the Advant Station 500 IMS User’s Guide for maintenance information. 


4.2 Error Messages 


4.2.1 Oracle oerr on-line tool 


Error messages related to Oracle tools can be investigated further by using the verr on-line tool 
from an IMS terminal window. This applies to all of the error messages issued by any of the 
installed Oracle tools. These types of messages are presented in two ways: 


° In interactive mode (for example when using the Object Presentations) the message 
(starting with the ORA number) is displayed at the bottom line of the window 


° In a trace file. This occurs when a failure in hardware or software (system or an Oracle 
tool) prevents an instance from continuing work. 


The trace files reside in the directory /var/opt/advant/log/oracle. The files are in 
ascii format. To find the trace file of interest for your problem, check the date of the files. Type 
the file to get the error number and use cerr to get a description. 


Example: 


To get a better description of the Oracle message ORA-6100 than what is supplied by the 
message itself: 


1. Open a terminal window. 
2. Entercommand: oerr ora 6100 


This provides the cause of the error as well as a suggestion on what action you should take to fix 
the problem. 


4.3 FAQ (Frequently Asked Questions) 


Q How do I execute operations from Microsoft Excel? 


A MS Excel can not present data from PL/SQL functions with OUT parameters (as most 
SQL*Connect Programming functions has). However, there exists a workaround, you must 
create a procedure (with only IN parameters) that calls the SQL*Connect procedure, stores 
the result in a temporary table, select data from temporary table into Excel and finally 
deletes the temporary table. 
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Appendix A Declarations for the SQL*Connect Programming 


A.1 Data Types 


The following data types are pre-defined in the GT package: 


TYPE IntArray IS TABLE OF NUMBER 
INDEX BY BINARY_INTEGER; 


The IntArray data type also applies for arrays of DEC, DECIMAL, DOUBLE PRECISION, 
FLOAT, INTEGER, INT, NUMERIC, REAL and SMALLINT data types. 


T, 


TYPE StringArray IS TABLE OF VARCHAR2 (256) 
INDEX BY BINARY_INTEGER; 


TYPE RowIdArray IS TABLE OF ROWID 
INDEX BY BINARY_INTEGER; 


TYPE DataArray IS TABLE OF LONG 


INDEX BY BINARY_INTEGER; 


TYPE AccessStatus IS RECORD ( 
codes NUMBER, 
flags NUMBER) ; 


A.2 Constants 


All constants described in this chapter are declared in the GT package. Below you find an 
example that shows how to use some of the constants. 


DECLARE 
status GT .AccessStatus; 
result NUMBER; 
value FLOAT; 
BEGIN 
result := gtAI.get_VALUE(‘*AIC71_1’, value, status); 
IF result != GT.SUCCESS THEN 
DBMS_OUTPUT.PUT_LINE(‘Function error = * || result); 
END IF; 
IF status.codes != GT.OBJ_SUCCESS THEN 


DBMS_OUTPUT.PUT_LINE(‘Access status codes 
DBMS_OUTPUT.PUT_LINE(‘Access status flags 
END IF; 


status.codes) ; 
status.flags); 


| 
eli 


END; 
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A.2.1 Common constants 


A-2 


Table A-1. GT Common Constants 


Constant Description 
OPEN_ARRAY_IS_EMPTY Represent an empty open array 
ATTRIBUTE Element type is an attribute 
OPERATION Element type is an operation 
EVENT Element type is an event 


Table A-2. GT Data Type Constants 


Constant Oracle Type 
INVALID_DATA_TYPE - 
SMALL_DATA_TYPE NUMBER 
SHORT_DATA_TYPE NUMBER 
LONG_DATA_TYPE NUMBER 
USMALL_DATA_TYPE NUMBER 
USHORT_DATA_TYPE NUMBER 
ULONG_DATA_TYPE NUMBER 
FLOAT_DATA_TYPE FLOAT 
DOUBLE_DATA_TYPE DOUBLE PRECISION 
CHAR_DATA_TYPE VARCHAR2 
BOOLEAN_DATA_TYPE BOOLEAN 
SHORT_BITSET_DATA_TYPE NUMBER 
BITSET_DATA_TYPE NUMBER 
STRING_DATA_TYPE VARCHAR2 
SHORT_ENUM_DATA_TYPE NUMBER 
ENUM_DATA_TYPE NUMBER 
STRUCT_DATA_TYPE RECORD 
UNION_DATA_TYPE RECORD 
ARRAY_DATA_TYPE TABLE 
OPEN_ARRAY_DATA_TYPE RECORD 
COMPOSITION_DATA_TYPE STRUCT 
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Table A-2. GT Data Type Constants (Continued) 


Constant 


Oracle Type 


OPERATION_TYPE 


EVENT_TYPE 


LAST_DATA_TYPE 


Table A-3. GT Data Type Direction Constants 


Constant Description 
DATA_IN Input data 
DATA_OUT Output data 
DATA_IN_ OUT In and Output data 


A.2.2 Function return status codes 


Table A-4. Function Return Status Codes 


Name Id Description 
TIMEOUT -126 | Communication service time-out 
ALLOCATION -124 | Could not allocate resource 
REFERENCE -123 | Illegal unique identity 
ILLEGAL_NAME -122 |A specified symbol uses illegal characters 
ILLEGAL_TYPE -116 | Illegal object type name 
NO_PRIVILEGE -112 | Insufficient privilege 
NO_MATCHING_CAP -100 |All capabilities are erroneous or pending 
NO_ASSOCIATION -98 |No subscription exists 
NO_TRANSLATION -95 |Could not translate name to identifier 
ERRONEOUS _ CAPS -84 |One or more capabilities are erroneous 
RESOURCE_LACK -18 |Lack of resources (memory) 
EXE FAILED -17 |Operation could not be executed 
ERR_EVSIZE -16 |Error in eventSize specification 
ERR_OPSIZE -15 |Error in operSize specification 
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Table A-4. Function Return Status Codes (Continued) 


Name Id Description 
ERR_VALSIZE -14 |Error in valueSize specification 
ERR_EVENT -13 | Error in event specification 
ERR_OPER -12 | Error in operation specification 
ERR_ATTRIB -11. | Error in attribute specification 
ERR_TIMEOUT -10 | Time out value out of range 
ILLEGAL_ROWID 9 Row ID illegal 
EMPTY_BUFFER -8 Buffer is empty 
ALREADY_DEFINED -7 Subscription already defined 
SUCCESS 1 Service was successfully completed 
MORE 2 More data available 


A.2.3 Object access status codes 


A.2.3.1 Status Code 


Table A-5. Access Status Codes 


Name Id Description 
CAP_INCONSISTENCY -120 | Capability is not in a consistent state 
CAP_ARRAY_BOUNDS -119 | Mismatch in open array bounds 
CAP_UNION_TAG -118 | Invalid tag or union 
OBJ_NOT_RESOLVED -117 | Object could not be resolved 
OBJ_UNREGISTERED -116 | Object not registered 
OBJ_OBJECT_MOVED -115 | Object moved 
OBJ _NODE_ DOWN -114 | Object’s node not reachable 
OBJ_NODE_UP -113 | Object’s node now reachable again 
OBJ _REQUEST_TIMEOUT -112 | Communication time-out 
OBJ_ TIMEOUT -111 | Cyclic time-out 
OBJ_COMM_FAIL -110 | Communication failure 
OBJ_ RESTARTED -109 | OMF has restarted 
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A.3 Capabilities 
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Table A-5. Access Status Codes (Continued) 


Name Id Description 
OBJ_ PENDING -108 | Communication failure 
OBJ_PING_TIMEOUT -107 | Ping request has timed out 
OBJ_FAILURE -64 | Generic method failure 
OBJ_ PARAMETER -63 | Parameter error in operation 
OBJ_ PERMISSION -62 | User not permitted to access element 
OBJ_STATUS1 - -61 - | Customized object status. Dependent on the 
OBJ_STATUS32 -30 | specific object server") 
OBJ_ SUCCESS 1 Successful access of object 
OBJ_LAST 127 |Last status code 


(1) See the Advalnform Object Types Reference Manual. 


Table A-6. Access Status Flag Codes 


Name Id Description 
OBJ_NO_FLAG 0 No flag value 
OBJ_CHANGED 1 Value changed since last get 
OBJ_DATA_LOST 2 Data lost after this value 
OBJ_ REFRESHED 4 Value is new due to refresh 
OBJ_SUSPENDED 8 Object association has been suspended 
OBJ_ EXTENDED 16 | Value due to extended association 
OBJ REDUCED 32 =| Association has been removed 
OBJ_TERMINATED 64 | Object association has been terminated 
OBJ_RENAMED 128 | Object has been renamed 
OBJ_SERVER_BUSY 256 | Object request in use by server 
OBJ_SERVER_PENDING 512 | Object data might not be consistent 


Capabilities are mentioned among the status codes. A capability is the name of the smallest part 
in a object request. For example, if you read several attributes from one object is each attribute 


request one capability. 
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A.4 Basic Object Packages 


A.4.1 gtAl 


A-6 


Refer to the Advalnform Object Types Reference Manual for more information on process 


objects. 


Package for the AI object type. 


Table A-7. AI Object Type Functions 


9/5 

Oo > 

Attribute Datatype 3 o Oo z 

3 |e 

°1 8 
NAME VARCHAR2(256) X 
DESCRIPTION VARCHAR2(28) X 

STATUS NUMBER(10) Xe |x 
STATUS_UPD_BLK BOOLEAN xX |X 
STATUS_ALARM_BLK") BOOLEAN xX 
STATUS_PRINT_BLK BOOLEAN X 
UNIT VARCHAR2(6) X 
RANGE_MIN FLOAT(24) X 
RANGE_MAX FLOAT(24) X 

VALUE FLOAT(24) xX |X |X |x 
ERROR_TREAT NUMBER X 

NO_OF_DEC NUMBER(3) xX |X |x 
SUBSYSTEM NUMBER(3) X 
CLASS NUMBER(3) X 
HI_LIM2 FLOAT(24) an 
HI_LIM1 FLOAT(24) xX |X 
LO_LIM1 FLOAT(24) xX |X 
LO_LIM2 FLOAT(24) xX |X 
USE_HI_LIM2 NUMBER X 
USE_HI_LIM1 NUMBER X 
USE_LO_LIM1 NUMBER X 
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Table A-7. AI Object Type Functions (Continued) 


2] s 
~|~-/ oO) g 
Attribute Datatype 2/23/68] c 
2 |e 
fo) ® 
ro) 
USE_LO _LIM2 NUMBER 
LIM1_ TREAT NUMBER(5) 
LIM2_ TREAT NUMBER(5) 
(1) The DISTURBANCE bit is also set 
Example 
The get functions for STATUS attribute value would be: 
gtAL .get_STATUS ( 
objectName IN VARCHAR2, 
value OUT NUMBER, 
accessStatus OUT GT .AccessStatus) ; 
gtAL .get_STATUS ( 
uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2) ; 
gtAI .get_STATUS ( 
uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2, 
value OUT NUMBER, 
accessStatus OUT GT .AccessStatus) ; 
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A.4.2 gtAO 


A-8 


Package for the AO object type. 


Table A-8. AO Object Type Functions 


e | § 
Oo > 
Attribute Datatype 2 o Oo ra 
3 | 2 
5 
NAME VARCHAR2(256) X 
DESCRIPTION VARCHAR2(28) X 
STATUS NUMBER(10) X X X 
STATUS_MAN_MODE BOOLEAN X X 
STATUS_OUTP_BLK BOOLEAN X X 
STATUS_ALARM_BLK BOOLEAN X X 
STATUS_PRINT_BLK BOOLEAN X X 
UNIT VARCHAR2(6) X 
RANGE_MIN FLOAT(24) X 
RANGE_MAX FLOAT(24) X 
VALUE FLOAT(24) X X X X 
MAX_LIM FLOAT(24) X 
MIN_LIM FLOAT(24) X 
START_VALUE NUMBER X 
ERROR_TREAT NUMBER X 
NO_OF_DEC NUMBER(3) X X X 
SUBSYSTEM NUMBER(3) X 
CLASS NUMBER(3) X 
Example 
And the getCyclic function for STATUS attribute value would be: 
gtAO.getCyclic_STATUS ( 
objectName IN VARCHAR2, 
cycleTime IN DOUBLE PRECISION) ; 
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A.4.3 gtDI 


Package for the DI object type. 


Table A-9. DI Object Type Functions 


[S) = 

Attribute Datatype 2/3/fg/% 

3/2 

om (<b) 

to) 
NAME VARCHAR2(256) X 
DESCRIPTION VARCHAR2(28) X 

STATUS NUMBER(10) x |x |x 
STATUS_UPD_BLK BOOLEAN xX |x 
STATUS_ALARM_BLK BOOLEAN xX |x 
STATUS_PRINT_BLK BOOLEAN xX |x 
STATUS_ VALUE BOOLEAN xX |x 
ERROR_TREAT NUMBER X 
VALUE_TREAT NUMBER X 
SUBSYSTEM NUMBER(3) X 
CLASS NUMBER(3) X 


Example 
The put functions for STATUS attribute value would be: 


gtDI .put_STATUS ( 


objectName IN VARCHAR2, 
value IN NUMBER, 
accessStatus OUT GT .AccessStatus) ; 


gtDI .put_STATUS ( 


uniquelIdentity IN NUMBER, 

objectName IN VARCHAR2, 

value IN NUMBER (10) ) ; 
gtDI.put_STATUS ( 

uniquelIdentity IN NUMBER, 

objectName IN VARCHAR2, 


accessStatus OUT GT .AccessStatus) ; 
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A.4.4 gtDO 


A-10 


Package for the DO object type. 


Table A-10. DO Object Type Functions 


[S) =< 

Attribute Datatype il) Oe ee le 

3 |e 

to) o 

to) 
NAME VARCHAR2(256) X 
DESCRIPTION VARCHAR2(28) X 

STATUS NUMBER(10) x |x |x 
STATUS_MAN_MODE BOOLEAN x |X 
STATUS_OUTP_BLK BOOLEAN x |x 
STATUS_ALARM_BLK BOOLEAN x |x 
STATUS_PRINT_BLK BOOLEAN x |X 
STATUS_ VALUE BOOLEAN x |X 
ERROR_TREAT NUMBER X 
SUBSYSTEM NUMBER(3) X 
CLASS NUMBER(3) X 

Example 


The getOnEvent function for STATUS attribute value would be: 


gtDO.getOnEvent_STATUS ( 
objectName IN VARCHAR2) ; 
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Package for the DAT object type. 


Table A-11. DAT Object Type Functions 


Attribute Datatype put | get | getCyclic | getOnEvent 

NAME VARCHAR2(256) X 

VALID NUMBER(3) X X 
VAL_TYPE NUMBER(3) X 

BO_VAL BOOLEAN X X 

B1_VAL - B31_VAL | BOOLEAN X 

IW_VAL NUMBER(5) X X 

IL_VAL NUMBER(10) X X X 

R_VAL FLOAT (24) X 

Example 


The getCyclic function for VALID attribute value would be: 


gtDAT.getCyclic_VALID ( 
objectName 
cycleTime 


Package for the TEXT object type. 


Table A-12. TEXT Object Type Functions 


VARCHAR2, 
DOUBLE PRECISION) ; 


eg..(|| 
Attribute Datatype 3. | lh line 
3/2 
om o 
to) 
NAME VARCHAR2(256) X 
INT_LONG NUMBER(10) X X 
TEXT_REAL FLOAT(24) X 
DISPMAX FLOAT(24) X 
DISPMIN FLOAT(24) X 
NO_OF_DEC NUMBER(3) x |x |x 


3BSE 014 220R0001 


A-11 


Advalnform® SQL*Connect® Programming User’s Guide 
Appendix A Declarations for the SQL*Connect Programming 


A-12 


Table A-12. TEXT Object Type Functions (Continued) 


58 

— — 3 > 

Attribute Datatype Beal oe 

3 | 2 

fo) ® 

fo) 
ORD_BLK NUMBER(3) X 

STATUS NUMBER(5) x |x |x 
STATUS. MAN BOOLEAN x |x 
STATUS_ TBOOLEAN BOOLEAN xX |x 
STATUS. B1_VAL BOOLEAN xX |x 
STATUS_ B2_VAL BOOLEAN xX |x 
STATUS_B3_ VAL BOOLEAN xX |x 
STATUS. B4_VAL BOOLEAN xX |x 

TEXT VARCHAR2(72) x |x |x |x 

Example 


The get functions for ORD_BLK attribute value would be: 


gt TEXT .get_ORD_BLK ( 
objectName 
value 
accessStatus 


gt TEXT .get_ORD_BLK ( 
uniquelIdentity 
objectName 


gt TEXT .get_ORD_BLK ( 
uniquelIdentity 
objectName 
value 
accessStatus 


IN 
OUT 
OUT 


IN 
IN 


IN 
IN 
OUT 
OUT 


VARCHAR2, 
NUMBER, 
GT .AccessStatus) ; 


NUMBER, 
VARCHAR2) ; 


NUMBER, 

VARCHAR2, 

NUMBER, 

GT .AccessStatus) ; 
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A.4.7 gtPIDCON 


Package for the PIDCON object type. 


Table A-13. PIDCON Object Type Functions 


2 | § 

Oo > 

Attribute Datatype ee ae caller- 

3 | 

2) & 
NAME VARCHAR2(256) X 
DESCRIPTION VARCHAR2(28) X 
MUNIT VARCHAR2(6) X 
E1_NAME VARCHAR2(20) X 
E2 NAME VARCHAR2(20) X 
E3 NAME VARCHAR2(20) X 

MNO_OF_DEC NUMBER(3) X |X |x 
P1NO_OF DEC NUMBER(3) x 
CLASS NUMBER(3) X 
SUBSYSTEM NUMBER(3) X 

STATUS_1 NUMBER(10) xX |X |x 
STATUS_1_ALARM_F1_BLK BOOLEAN X 
STATUS_1_ALARM_F2_BLK BOOLEAN X 

STATUS. 2 NUMBER(10) xX |X |x 
STATUS_2_MMI_INT_BLK BOOLEAN X |X 
STATUS_2 MMI_DER_BLK BOOLEAN X 
STATUS. 3 NUMBER(10) X 
STATUS_4 NUMBER(10) X 
STATUS_4 PRINT_F1_BLK BOOLEAN X 
STATUS_4 PRINT_F2_BLK BOOLEAN X 

MV FLOAT(24) xX |x |x 

AUTOSP FLOAT(24) xX |X |x 

wsP FLOAT(24) xX |X |x 

DEVIATION FLOAT(24) X |X |x 
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Table A-13. PIDCON Object Type Functions (Continued) 


2| 5 
re) > 
Attribute Datatype 3 o oO Fo 
3 | 
es 
OUT FLOAT(24) x |x |x 
TS FLOAT(24) xX 4 » 4 
MAN_OUT FLOAT(24) xX xX xX 
EXT _OUT_LL FLOAT(24) xX xX » 4 
EXT _OUT_HL FLOAT(24) xX xX xX 
EXT_GAIN FLOAT(24) 4 4 xX 
EXT_TI FLOAT(24) » 4 4 4 
EXT_TD FLOAT(24) xX xX »4 
EXT_TF FLOAT(24) xX 4 xX 
POUT FLOAT(24) xX xX » 4 
PRES1 FLOAT(24) xX xX xX 
PRES2 FLOAT(24) xX 4 » 4 
MRANGE_MIN FLOAT(24) xX 
MRANGE_MAX FLOAT(24) xX 
MMI SPL FLOAT(24) xX xX 
MMI SPH FLOAT(24) xX xX 
MMI MVL2 FLOAT(24) xX xX 
MMI MVL1 FLOAT(24) xX 4 
MMI MVH1 FLOAT(24) xX xX 
MMI MVH2 FLOAT(24) xX 4 
MMI DEVL FLOAT(24) » 4 xX 
MMI_DEVH FLOAT(24) xX xX 
MMI SP FLOAT(24) 4 xX 
MMI MAN_OUT FLOAT(24) xX xX 
MMI_GAIN FLOAT(24) xX 4 
MMI TI FLOAT(24) xX xX 
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Table A-13. PIDCON Object Type Functions (Continued) 


2 | 5 
— — 7 > 
Attribute Datatype 3/9/83 /|'e 
3 | 2 
D> o 
D 
MMI_TD FLOAT(24) xX xX 
MMI_TF FLOAT(24) xX 4 
MMI_OUT_LL FLOAT(24) X X 
MMI_OUT_HL FLOAT(24) X X 
DEADZ FLOAT(24) xX 4 
P1RANGE_MIN FLOAT(24) 4 
P1RANGE_MAX FLOAT(24) 4 
PERC_MIN FLOAT(24) xX 
PERC_MAX FLOAT(24) 4 
Example 
The get functions for MV attribute value would be: 
gtPIDCON.get_MV ( 
objectName IN VARCHAR2, 
value OUT FLOAT, 
accessStatus OUT GT .AccessStatus) ; 
gtPIDCON.get_MV ( 
uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2) ; 
gtPIDCON.get_MV ( 
uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2, 
value OUT FLOAT, 
accessStatus OUT GT .AccessStatus) ; 
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A.4.8 gtRATIOSTN 


A-16 


Package for the RATIOSTN object type. 


Table A-14. RATIOSTN Object Type Functions 


e | § 
3 | > 
Attribute Datatype 2 o Oo ra 
2 |° 
=| 8 
NAME VARCHAR2(256) X 
DESCRIPTION VARCHAR2(28) xX 
MNO_OF_DEC NUMBER(3) 4 
PONO_OF_DEC NUMBER(3) xX xX xX 
CLASS NUMBER(3) X 
SUBSYSTEM NUMBER(3) xX 
STATUS _1 NUMBER(10) » 4 » 4 xX 
STATUS_1_ALARM_F1_BLK BOOLEAN xX 
STATUS_1_ALARM_F2_ BLK BOOLEAN xX xX 
STATUS _ 2 NUMBER(10) xX 
STATUS_3 NUMBER(10) X 
STATUS _4 NUMBER(10) 4 
STATUS 4 PRINT_F1i_BLK BOOLEAN xX 
STATUS 4 PRINT _F2_BLK BOOLEAN xX xX 
MV FLOAT(24) 4 4 xX 
RATIOREF FLOAT(24) 4 4 »4 
WRATIO FLOAT(24) xX xX »4 
OUT FLOAT(24) x |x |x 
MAN_OUT FLOAT(24) xX xX xX 
TS FLOAT(24) 4 xX xX 
EXT _OUT_LL FLOAT(24) xX 4 »4 
EXT _OUT_HL FLOAT(24) xX xX 4 
POUT FLOAT(24) xX xX xX 
PRES1 FLOAT(24) xX 4 xX 
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Table A-14. RATIOSTN Object Type Functions (Continued) 


e | § 
— — 3 > 
Attribute Datatype 3.) Oe |e 
2 |e 
a co) 
Do 
MRANGE_MIN FLOAT(24) xX 
MRANGE_MAX FLOAT(24) 4 
MMI RATIOL FLOAT(24) Xx xX 
MMI RATIOH FLOAT(24) 4 » 4 
MMI MVL2 FLOAT(24) 4 xX 
MMI MVL1 FLOAT(24) 4 4 
MMI_MVH1 FLOAT(24) xX 4 
MMI MVH2 FLOAT(24) xX xX 
MMI_RATIOREF FLOAT(24) xX xX 4 4 
MMI MAN OUT FLOAT(24) 4 xX xX xX 
MMI BIAS FLOAT(24) xX xX 4 4 
MMI OUT_LL FLOAT(24) xX xX xX xX 
MMI_OUT_HL FLOAT(24) Xx xX xX xX 
MUNIT VARCHAR(6) 4 
RUNIT VARCHAR(6) xX 
POUNIT VARCHAR(6) xX 
E1_ NAME VARCHAR(20) xX 
Example 
The get functions for OUT attribute value would be: 
gtRATIOSTN.get_OUT ( 
objectName IN VARCHAR2, 
value OUT FLOAT, 
accessStatus OUT GT .AccessStatus) ; 
gtRATIOSTN.get_OUT ( 
uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2) ; 
gtRATIOSTN.get_OUT ( 
uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2, 
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A.4.9 gtMANSTN 


A-18 


value 


accessStatus 


Package for the MANSTN object type. 


OUT 
OUT 


FLOAT, 
GT .AccessStatus) ; 


Table A-15. MANSTN Object Type Functions 


o | § 

ge) Soe Nal 

Attribute Datatype 3 | @ g 5 

>) 5 
NAME VARCHAR2(256) X 
DESCRIPTION VARCHAR2(28) X 
MNO_OF_DEC NUMBER(3) X 
PONO_OF_DEC NUMBER(3) X 
P1NO_OF_DEC NUMBER(3) X 
CLASS NUMBER(3) X 
SUBSYSTEM NUMBER(3) X 

STATUS _1 NUMBER(10) x pe” x 
STATUS_1_ALARM_F1_BLK BOOLEAN X |X 
STATUS_1_ALARM_F2_BLK BOOLEAN X 
STATUS 2 NUMBER(10) X 
STATUS_3 NUMBER(10) X 

STATUS _4 NUMBER(10) x |X |x 
STATUS_4 PRINT_F1_BLK BOOLEAN xX |X 
STATUS_4 PRINT F2 BLK BOOLEAN X 

MV FLOAT(24) x |x |x 

OUTREF FLOAT(24) x |X |X 

OUT FLOAT(24) x |x |X |X 

TS FLOAT(24) x |x |x 

POUT FLOAT(24) x |X [Xx 

PRES1 FLOAT(24) x |X |x 
MRANGE_MIN FLOAT(24) X 
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Table A-15. MANSTN Object Type Functions (Continued) 


e | § 
Attribute Datatype 3.) Oe |e 
2 |e 
a co) 
Do 
MRANGE_MAX FLOAT(24) xX 
MMI MVL2 FLOAT(24) xX xX 
MMI MVL1 FLOAT(24) Xx 4 
MMI_MVH1 FLOAT(24) xX » 4 
MMI MVH2 FLOAT(24) xX xX 
MMI_OUT_REF FLOAT(24) xX 
PORANGE_MIN FLOAT(24) 4 
PORANGE_MAX FLOAT(24) xX 
MMI_OUT_LL FLOAT(24) 4 
MMI_OUT_HL FLOAT(24) xX xX 
P1RANGE_MIN FLOAT(24) xX 
P1RANGE_MAX FLOAT(24) xX 
PERC_MIN FLOAT(24) xX 
PERC_MAX FLOAT(24) xX 
MUNIT VARCHAR(6) xX 
POUNIT VARCHAR(6) xX 
P1UNIT VARCHAR(6) X 
E1_ NAME VARCHAR(20) X 
Example 
The get functions for TS attribute value would be: 
gtMANSTN.get_TS ( 
objectName IN VARCHAR2, 
value OUT FLOAT, 
accessStatus OUT GT .AccessStatus) ; 
gtMANSTN.get_TS ( 
uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2) ; 
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gtMANSTN.get_TS ( 


uniquelIdentity IN NUMBER, 
objectName IN VARCHAR2, 

value OUT FLOAT, 
accessStatus OUT GT .AccessStatus) ; 


A.5 History Package - gtHistory 


A.5.1 Data Types 


These data types are pre-defined in the gtHISTORY package: 


TYPE NUMERIC_ENTRY_UT IS RECORD ( 


max_is NUMBER, 
last_is NUMBER, 
seconds GT.IntArray, 
microSeconds GT.IntArray, 
entryValue GT.IntArray, 
entryStatus GT.IntArray, 
objectStatus GT.IntArray) ; 
TYPE MESSAGE_ENTRY_LUT IS RECORD ( 
max_is NUMBER, 
last_is NUMBER, 
localSeconds GT.IntArray, 
localMicroSeconds GT.IntArray, 
utcSeconds GT.IntArray, 
utcMicroSeconds GT.IntArray, 
historyMsgID GT.IntArray, 
msgCount GT.IntArray, 
entryStatus GT.IntArray, 
message GT.StringArray, 
procOb Name GT.StringArray, 
sectionName GT.StringArray, 
batchID GT.StringArray, 
unitID GT.StringArray, 
sequenceID GT.StringArray, 
eventReason GT.IntArray, 
eventProperty GT.IntArray, 
netwID GT.IntArray, 
nodeID GT.IntArray, 
priority GT.IntArray, 
msgType GT.IntArray) ; 
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Table A-16. Time justification constants 


Constant Description 
hsSTART_TIME Select entries up to time 
hsEND_TIME Select entries ends with time 


hsFROM_START 


Select entries from time 


Table A-17. Time type constants 


Constant Description 
hsPRESENT Present time 
hsLOCAL Local time 
hsUTC Universal time 
Table A-18. Data collection constants 
Constant Description 
hsRAW Raw data 


hsINTERPOLATE 


Interpolated data 


hsINTERPOLATE_ENDS 


Interpolated 


hsTREND 


Trend data 


hsSECONDARY_RAW 


Secondary raw data 


hsDISPLAY 


Display retrieval data 


hsNO_OF_RTRV_TYPES 


No of retrieval type 


Table A-19. Sort order constants 


Constant 


Description 


hsASCENDING 


Ascending entry sort order 


hsDESCENDING 


Descending entry sort order 
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A-22 


Table A-20. Entry direction constants 


Constant Description 
hsFORWARD Direction forward 
hsBACKWARD Direction backward 

Table A-21. Data selector constants 

Constant Description 
hsCURRENT Current data 
hsORIGINAL Original data (no modified data) 

Table A-22. Algorithm constants 

Constant Description 
hsAVERAGE Average algorithm 
hsMAXIMUM Maximum algorithm 
hsMINIMUM Minimum algorithm 


hsINSTANTANEOUS 


Instantaneous algorithm 


hsSUM 


Sum algorithm 


hsSUM_OF_SQRS 


Sum of square roots algorithm 


hsSTANDARD_DEV 


Standard deviation algorithm 


hsNUM_OF_VALUES 


Number of values algorithm 


hsWILDCARD Wildcard algorithm 
Table A-23. Message type constants 
Constant Description 
hsUNTYPED Untyped message 
hsALARM Alarm message 


hsBILLBOARD 


Billboard message 


hsPARAMETER_CHANGE 


Parameter change message 


hsLADDER_LOGICG 


Ladder logic message 


hsSPC 


SPC message 


hsALARM_ACK 


Alarm acknowledge 
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Table A-23. Message type constants (Continued) 


Constant 


Description 


hsDIAGNOSTIC 


Diagnostic message 


hsBATCH_MSG 


Batch message 


Table A-24. Message key type constants 


Constant 


Description 


hsALL_MESSAGES 


All messages 


hsPROCESS_OBJECT 


Process objects 


hsSECTION_NAME 


Section name 


hsBATCH_ID Batch ID 
hsUNIT_ID Unit ID 
hsSEQUENCE_ID Sequency ID 


hsEVENT_PROPERTY 


Event property 


hsNETWORK_ID 


Network ID 


hsNODE_ID 


Node ID 


hsMSG_PRIORITY 


Messages Priority 


Table A-25. Access Status Code constants 


Constant 


Description 


hsCAP_INVALID_PARAMS 


Parameter error in operation 


hsCAP_PERMISSION 


Not permitted to access object 


hsCAP_NO_DATA_OLD 


No data found for request 


hsCAP_AT_END 


Request reached end of log, more data may be 
in archives 


hsCAP_SYSTEM_ERROR 


Error occurred in Oracle, Unix, OTI, ... 


hsCAP_NOT_IMPLEMENTED 


Functionality not implemented 


hsCAP_OPS_INCOMPAT 


Multiple AlOs given 


hsCAP_INV_ATTR 


Attribute is not valid for implementation 


hsCAP_ACCESS_NAME_INVALID 


Access name not defined in system 


hsCAP_INTERNAL_ERROR 


An internal error inconsistency 
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Table A-25. Access Status Code constants (Continued) 


Constant Description 
hsCAP_MORE_DATA More data is available than could be returned 
hsCAP_ALREADY_EXISTS Item being added, (object or entry), already 

exists 
hsCAP_FULL Container, (log, media, ...), is full 
hsCAP_INACTIVE Invalid request for an inactive log 
hsCAP_IN_USE Invalid request for log in use 
hsCAP_BAD_MEDIA Archive Media Failure 


A.6 Numerical Log Configuration Data Package - gtNLOG 


A.6.1 Data Types 
These data types are pre-defined in the gtNLOG package: 


TYPE ConfDataRecord IS RECORD ( 


NAME VARCHAR2 (82), 
ACCESS_NAME VARCHAR2 (64), 
DESCRIPTION VARCHAR2 (40), 
STATUS NUMBER (10), 
REDUNDANT_LOG_NAME VARCHAR2 (80), 
LOG_GROUP VARCHAR2 (32), 
LOG SET VARCHAR2 (32), 
ARCHIVE_GROUP VARCHAR2 (32), 
HIERARCHY_LEVEL NUMBER (3), 
SEQUENCE_NUM NUMBER (3), 
LOG_STARTUP_STATE NUMBER (10), 
LOG_START_TIMESECONDS NUMBER (10), 
LOG_START_TIMEMICROSECONDS NUMBER (10), 
LOG_END_TIMESECONDS NUMBER (10), 
LOG_END_TIMEMICROSECONDS NUMBER (10), 
FIRST_NON_ARCH_ENTRYSECONDS NUMBER (10), 
FIRST _NON_ARCH_ENTRYMSEC NUMBER (10), 
LOG_DATA_TYPE NUMBER (10), 
FIRST_ACT_TIMESECONDS NUMBER (10), 
FIRST_ACT_TIMEMICROSECONDS NUMBER (10), 
ALIGNMENT_TIMEUNIT VARCHAR2 (10), 
ALIGNMENT_TIMEPAD NUMBER (3), 
ALIGNMENT_TIMEVALUE NUMBER (5), 
COLLECTION_TYPE NUMBER (10), 
COLLECTION_MODE NUMBER (10), 
DATA SOURCE VARCHAR2 (80), 
LOG_TIME_PERIODUNIT VARCHAR2 (10), 
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LOG_TIME_PERIODPAD NUMBER (3), 
LOG_TIME_PERIODVALUE NUMBER (5), 
LOG_CAPACITY NUMBER (10), 
SAMPLE INTERVALUNIT VARCHAR2 (10), 
SAMPLE _INTERVALPAD NUMBER (3), 
SAMPLE _INTERVALVALUE NUMBER (5), 
SAMPLE BLOCKING _RATEUNIT VARCHAR2 (10), 
SAMPLE BLOCKING _RATEPAD NUMBER (3), 
SAMPLE BLOCKING _RATEVALUE NUMBER (5), 
CALC_ALGORITHM NUMBER (10), 
BAD_DQ_ LIMIT FLOAT (24), 
ENTRIES _FOR_CALC NUMBER (10), 
COMPACTION_DEADBAND FLOAT (24), 
LOG_ENG_UNIT VARCHAR2 (10), 
PRES_RANGE_MAX FLOAT (24), 
PRES_RANGE_MIN FLOAT (24), 
STORAGE_INTERVALUNIT VARCHAR2 (10), 
STORAGE_INTERVALPAD NUMBER (3), 
STORAGE_INTERVALVALUE NUMBER (5), 
ENG _RANGE_MAX FLOAT (24), 
ENG _RANGE_MIN FLOAT (24), 
HI LIMIT FLOAT (24), 
HI_HI_LIMIT FLOAT (24), 
LO_LIMIT FLOAT (24), 
LO_LO_LIMIT FLOAT (24), 
STATE_SET VARCHAR2 (32)); 
TYPE ConfDataArray IS RECORD ( 
nrOfLogs NUMBER, 
NAME GT.StringArray, 
ACCESS_NAME GT.StringArray, 
DESCRIPTION GT.StringArray, 
STATUS GT.IntArray, 
REDUNDANT_LOG_NAME GT.StringArray, 
LOG_GROUP GT.StringArray, 
LOG_SET GT.StringArray, 
ARCHIVE_GROUP GT.StringArray, 
HIERARCHY_LEVEL GT.IntArray, 
SEQUENCE_NUM GT.IntArray, 
LOG_STARTUP_STATE GT.IntArray, 
LOG_START_TIMESECONDS GT.IntArray, 
LOG_START_TIMEMICROSECONDS GT.IntArray, 
LOG_END_TIMESECONDS GT.IntArray, 
LOG_END_TIMEMICROSECONDS GT.IntArray, 
FIRST_NON_ARCH_ENTRYSECONDS GT.IntArray, 
FIRST_NON_ARCH_ENTRYMSEC GT.IntArray, 
LOG_DATA_TYPE GT.IntArray, 
FIRST_ACT_TIMESECONDS GT.IntArray, 
FIRST_ACT_TIMEMICROSECONDS GT.IntArray, 
ALIGNMENT_TIMEUNIT GT.StringArray, 
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ALIGNMENT_TIMEPAD GT.IntArray, 
ALIGNMENT_TIMEVALUE GT.IntArray, 
COLLECTION_TYPE GT.IntArray, 
COLLECTION_MODE GT.IntArray, 
DATA_SOURCE GT.StringArray, 
LOG_TIME_PERIODUNIT GT.StringArray, 
LOG_TIME_PERIODPAD GT.IntArray, 
LOG_TIME_PERIODVALUE GT.IntArray, 
LOG_CAPACITY GT.IntArray, 
SAMPLE_INTERVALUNIT GT.StringArray, 
SAMPLE_INTERVALPAD GT.IntArray, 
SAMPLE_INTERVALVALUE GT.IntArray, 
SAMPLE BLOCKING _RATEUNIT GT.StringArray, 
SAMPLE_BLOCKING_RATEPAD GT.IntArray, 
SAMPLE BLOCKING _RATEVALUE GT.IntArray, 
CALC_ALGORITHM GT.IntArray, 
BAD_DQ_ LIMIT GT.IntArray, 
ENTRIES _FOR_CALC GT.IntArray, 
COMPACTION_DEADBAND GT.IntArray, 
LOG_ENG_UNIT GT.StringArray, 
PRES_RANGE_MAX GT.IntArray, 
PRES_RANGE_MIN GT.IntArray, 
STORAGE_INTERVALUNIT GT.StringArray, 
STORAGE_INTERVALPAD GT.IntArray, 
STORAGE_INTERVALVALUE GT.IntArray, 
ENG_RANGE_MAX GT.IntArray, 
ENG_RANGE_MIN GT.IntArray, 
HI LIMIT GT.IntArray, 
HI _HI_LIMIT GT.IntArray, 
LO_LIMIT GT.IntArray, 
LO_LO_LIMIT GT.IntArray, 
STATE_SET GT.StringArray); 
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